Spans

Reference for client.spans in the Future AGI Python and TypeScript SDKs: spans.get, spans.list.

client.spans on fi.Client (Python) and client.spans on Client from @future-agi/sdk (TypeScript). The models these methods return are on Observability response models; how arguments, pagination, errors and strict mode work is in the overview.

Methods

MethodDescription
spans.getReturn an observation span by its identifier.
spans.listList observation spans using the supplied filters.

client.spans

spans.get

Return an observation span by its identifier.

GET /tracer/observation-span/{id}/

MCP tool: get_span

result = client.spans.get("your-id")
const result = await client.spans.get("your-id");
Signature
client.spans.get(
    id: str,
    *,
    test_execution_id: str | None | NotGiven = NOT_GIVEN,
    call_execution_id: str | None | NotGiven = NOT_GIVEN,
    project_id: str | None | NotGiven = NOT_GIVEN,
    trace_id: str | None | NotGiven = NOT_GIVEN,
    start_hour: str | None | NotGiven = NOT_GIVEN,
    observation_type: str | None | NotGiven = NOT_GIVEN,
    service_name: str | None | NotGiven = NOT_GIVEN,
    expected_start_time: str | None | NotGiven = NOT_GIVEN,
    expected_version: str | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.ObservationSpanDetailResult
client.spans.get(id: string, params: SpansGetParams = {}, options?: RequestOptions): Promise<models.ObservationSpanDetailResult>

export interface SpansGetParams {
  /** A run the caller can read; opens the hidden simulation project of that run's agent. */
  test_execution_id?: string | null;
  /** A run the caller can read; opens the hidden simulation project of that run's agent. */
  call_execution_id?: string | null;
  project_id?: string | null;
  trace_id?: string | null;
  start_hour?: string | null;
  observation_type?: string | null;
  service_name?: string | null;
  expected_start_time?: string | null;
  expected_version?: string | null;
}

Parameters

id string Required

Positional argument id.

test_execution_id string Optional

A run the caller can read; opens the hidden simulation project of that run’s agent.

call_execution_id string Optional

A run the caller can read; opens the hidden simulation project of that run’s agent.

project_id string Optional
trace_id string Optional
start_hour string Optional
observation_type string Optional
service_name string Optional
expected_start_time string Optional
expected_version string Optional

Returns

ObservationSpanDetailResult.

spans.list

List observation spans using the supplied filters.

GET /tracer/observation-span/list_spans_observe/

MCP tool: list_spans

result = client.spans.list()
const result = await client.spans.list();
Signature
client.spans.list(
    *,
    project_id: str | None | NotGiven = NOT_GIVEN,
    user_id: str | None | NotGiven = NOT_GIVEN,
    filters: str | None | NotGiven = NOT_GIVEN,
    page_number: int | None | NotGiven = NOT_GIVEN,
    page_size: int | None | NotGiven = NOT_GIVEN,
    cursor: str | None | NotGiven = NOT_GIVEN,
    cursor_mode: bool | None | NotGiven = NOT_GIVEN,
    allow_sampled: bool | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.SpanObserveListResult
client.spans.list(params: SpansListParams = {}, options?: RequestOptions): Promise<models.SpanObserveListResult>

export interface SpansListParams {
  project_id?: string | null;
  user_id?: string | null;
  filters?: string | null;
  /** Zero-based numbered page. Pages whose required ordered work exceeds the finite read contract return HTTP 422 with code page_depth_exceeded; request an earlier page or narrow the time range. */
  page_number?: number | null;
  page_size?: number | null;
  /** Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter. */
  cursor?: string | null;
  cursor_mode?: boolean | null;
  /** Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total, or true to opt in explicitly to lower-bound totals. */
  allow_sampled?: boolean | null;
}

Parameters

project_id string Optional
user_id string Optional
filters string Optional
page_number integer Optional

Zero-based numbered page. Pages whose required ordered work exceeds the finite read contract return HTTP 422 with code page_depth_exceeded; request an earlier page or narrow the time range.

page_size integer Optional
cursor string Optional

Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter.

cursor_mode boolean Optional
allow_sampled boolean Optional

Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total, or true to opt in explicitly to lower-bound totals.

Returns

SpanObserveListResult.

Was this page helpful?

Questions & Discussion