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
| Method | Description |
|---|---|
traces.error_analysis | Return the recorded error analysis for a trace. |
traces.get | Return a trace by its identifier. |
traces.list | Search traces using project, time range, status, and attribute filters. |
traces.properties.list | Discover filter properties from the shared metrics catalog. |
client.traces
traces.error_analysis
Return the recorded error analysis for a trace.
/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.TraceErrorAnalysisResultclient.traces.errorAnalysis(traceId: string, options?: RequestOptions): Promise<models.TraceErrorAnalysisResult> Parameters
Positional argument trace_id.
Returns
traces.get
Return a trace by its identifier.
/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.TraceDetailResultclient.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
Positional argument id.
A run the caller can read; opens the hidden simulation project of that run’s agent.
A run the caller can read; opens the hidden simulation project of that run’s agent.
Project the detail was opened from. The same id can exist in several projects; when supplied, only that project’s copy is read.
Returns
traces.list
Search traces using project, time range, status, and attribute filters.
/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.TraceObserveListResultclient.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
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.
Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter.
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.
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.
Returns
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.
/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.DashboardMetricsCatalogResultclient.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
observabilitydatasetsimulation system_metriceval_metricannotation_metriccustom_attributecustom_column metricdimension tracesspanssessionsusersvoice_callspromptsdatasetssimulationbothall Returns
Questions & Discussion