Traces

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

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

Methods

MethodDescription
traces.error_analysisReturn the recorded error analysis for a trace.
traces.getReturn a trace by its identifier.
traces.listSearch traces using project, time range, status, and attribute filters.
traces.properties.listDiscover filter properties from the shared metrics catalog.

client.traces

traces.error_analysis

Return the recorded error analysis for a trace.

GET /tracer/trace-error-analysis/{trace_id}/

MCP tool: get_trace_error_analysis

result = client.traces.error_analysis("your-trace-id")
const result = await client.traces.errorAnalysis("your-trace-id");
Signature
client.traces.error_analysis(
    trace_id: str,
    *,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.TraceErrorAnalysisResult
client.traces.errorAnalysis(traceId: string, options?: RequestOptions): Promise<models.TraceErrorAnalysisResult>

Parameters

trace_id string Required

Positional argument trace_id.

Returns

TraceErrorAnalysisResult.

traces.get

Return a trace by its identifier.

GET /tracer/trace/{id}/

MCP tool: get_trace

result = client.traces.get("your-id")
const result = await client.traces.get("your-id");
Signature
client.traces.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,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.TraceDetailResult
client.traces.get(id: string, params: TracesGetParams = {}, options?: RequestOptions): Promise<models.TraceDetailResult>

export interface TracesGetParams {
  /** 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 the detail was opened from. The same id can exist in several projects; when supplied, only that project's copy is read. */
  project_id?: 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

Project the detail was opened from. The same id can exist in several projects; when supplied, only that project’s copy is read.

Returns

TraceDetailResult.

traces.list

Search traces using project, time range, status, and attribute filters.

GET /tracer/trace/list_traces_of_session/

MCP tool: search_traces

result = client.traces.list()
const result = await client.traces.list();
Signature
client.traces.list(
    *,
    project_id: str | None | NotGiven = NOT_GIVEN,
    project_version_id: str | None | NotGiven = NOT_GIVEN,
    session_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,
    attribute_keys: str | None | NotGiven = NOT_GIVEN,
    allow_sampled: bool | None | NotGiven = NOT_GIVEN,
    interval: str | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.TraceObserveListResult
client.traces.list(params: TracesListParams = {}, options?: RequestOptions): Promise<models.TraceObserveListResult>

export interface TracesListParams {
  project_id?: string | null;
  project_version_id?: string | null;
  session_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;
  /** JSON-encoded list of custom attribute keys to hydrate; only requested keys are returned. Each key resolves to its latest live span value by (start_time, span_id). Comma-separated simple keys remain supported. */
  attribute_keys?: string | null;
  /** Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total. Send true to opt in explicitly to lower-bound totals and, on the first page, a clearly labelled bounded partial result when the full ordered prefix cannot be proven inside the read budget. */
  allow_sampled?: boolean | null;
  interval?: string | null;
}

Parameters

project_id string Optional
project_version_id string Optional
session_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
attribute_keys string Optional

JSON-encoded list of custom attribute keys to hydrate; only requested keys are returned. Each key resolves to its latest live span value by (start_time, span_id). Comma-separated simple keys remain supported.

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. Send true to opt in explicitly to lower-bound totals and, on the first page, a clearly labelled bounded partial result when the full ordered prefix cannot be proven inside the read budget.

interval string Optional

Returns

TraceObserveListResult.

client.traces.properties

TypeScript: client.traces.properties.

traces.properties.list

Discover filter properties from the shared metrics catalog. Pass cursor_mode=true, page_size (at most 50), source=traces (search_traces) or source=spans (list_spans), per_eval_config=true and project_ids when known. Use role=dimension to narrow to dimensions. Use name as column_id; set filter_config.col_type by mapping category system_metric to SYSTEM_METRIC, custom_attribute to SPAN_ATTRIBUTE, eval_metric to EVAL_METRIC, and annotation_metric to ANNOTATION. Preserve property_id and source for typed attribute bindings. Follow has_more/next_cursor by passing cursor; omit page and exclude_custom_attributes in cursor mode.

GET /tracer/dashboard/metrics/

MCP tool: list_trace_properties

result = client.traces.properties.list()
const result = await client.traces.properties.list();
Signature
client.traces.properties.list(
    *,
    workflow: Literal['observability', 'dataset', 'simulation'] | None | NotGiven = NOT_GIVEN,
    project_ids: str | None | NotGiven = NOT_GIVEN,
    agent_definition_id: str | None | NotGiven = NOT_GIVEN,
    per_eval_config: bool | None | NotGiven = NOT_GIVEN,
    exclude_custom_attributes: bool | None | NotGiven = NOT_GIVEN,
    search: str | None | NotGiven = NOT_GIVEN,
    category: Literal['system_metric', 'eval_metric', 'annotation_metric', 'custom_attribute', 'custom_column'] | None | NotGiven = NOT_GIVEN,
    role: Literal['metric', 'dimension'] | None | NotGiven = NOT_GIVEN,
    source: Literal['traces', 'spans', 'sessions', 'users', 'voice_calls', 'prompts', 'datasets', 'simulation', 'both', 'all'] | None | NotGiven = NOT_GIVEN,
    page: int | None | NotGiven = NOT_GIVEN,
    page_size: int | None | NotGiven = NOT_GIVEN,
    cursor_mode: bool | None | NotGiven = NOT_GIVEN,
    cursor: str | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardMetricsCatalogResult
client.traces.properties.list(params: TracesPropertiesListParams = {}, options?: RequestOptions): Promise<models.DashboardMetricsCatalogResult>

export interface TracesPropertiesListParams {
  workflow?: "observability" | "dataset" | "simulation" | null;
  project_ids?: string | null;
  agent_definition_id?: string | null;
  per_eval_config?: boolean | null;
  exclude_custom_attributes?: boolean | null;
  search?: string | null;
  category?: "system_metric" | "eval_metric" | "annotation_metric" | "custom_attribute" | "custom_column" | null;
  role?: "metric" | "dimension" | null;
  source?: "traces" | "spans" | "sessions" | "users" | "voice_calls" | "prompts" | "datasets" | "simulation" | "both" | "all" | null;
  page?: number | null;
  page_size?: number | null;
  cursor_mode?: boolean | null;
  cursor?: string | null;
}

Parameters

workflow string Optional
Allowed values:
observabilitydatasetsimulation
project_ids string Optional
agent_definition_id string Optional
per_eval_config boolean Optional
exclude_custom_attributes boolean Optional
search string Optional
category string Optional
Allowed values:
system_metriceval_metricannotation_metriccustom_attributecustom_column
role string Optional
Allowed values:
metricdimension
source string Optional
Allowed values:
tracesspanssessionsusersvoice_callspromptsdatasetssimulationbothall
page integer Optional
page_size integer Optional
cursor_mode boolean Optional
cursor string Optional

Returns

DashboardMetricsCatalogResult.

Was this page helpful?

Questions & Discussion