--- title: "List spans in a trace" method: GET path: "/v2/agent_analytics/traces/{trace_id}/spans" tags: ["Agent Analytics"] --- # List spans in a trace `GET /v2/agent_analytics/traces/{trace_id}/spans` Returns the flat list of spans for a given trace. Each span includes its parent_span_id so you can reconstruct the tree. ## Path parameters - `trace_id` string, required ## Query parameters - `include_content` boolean - `operation` 'invoke_agent' | 'chat' | 'execute_tool' | 'thinking' | 'output' | 'step_transition' | 'image_read' | 'compaction' - `parent_span_id` string - `exclude_subagents` boolean - `limit` integer - `page_key` string ## Headers - `Request-Timeout` integer - `Request-Timeout-Millis` integer ## Response `200` List of spans in the trace. - ListAgentTraceSpansResponse — A list of spans for an agent trace. - `spans` AgentTraceSpan[], required — The list of spans. - union — A single span within an agent trace. The shape of attributes and content varies by operation type. - object — Common properties shared by all agent trace span types. - `span_id` string, required — The unique identifier of the span. - `parent_span_id` string, nullable — The identifier of the parent span, if any. - `trace_id` string, required — The identifier of the trace this span belongs to. - `started_at` string, date-time, required — The time this span started. - `duration_ms` integer — Duration of this span in milliseconds. - `status` 'ok' | 'error', required — The status of an agent trace span. - `error_message` string, nullable — The error message when the span status is error. - `step_name` string, nullable — The name of the agent step active when this span was created. - `has_children` boolean, required — Whether this span has child spans. - `operation` string, required — The operation type for this span. - `attributes` InvokeAgentSpanAttributes — Attributes for an invoke_agent span. - `model` string — The LLM model used in this invocation. - `input_tokens` integer — Total input tokens consumed across all LLM calls in this invocation. - `output_tokens` integer — Total output tokens produced across all LLM calls in this invocation. - `cache_read_input_tokens` integer — Number of input tokens read from cache. - `temperature` number, double — The temperature parameter used for generation. - `max_tokens` integer — The maximum tokens parameter used for generation. - `provider_name` string — The LLM provider name. - `agent_name` string — The name of the agent. - `agent_description` string — The description of the agent. - `output_type` 'text' | 'json' — The requested output format of the agent invocation. - `input_event_id` string — The event ID of the input message. - `output_event_id` string — The event ID of the output message. - `input_files` AgentTraceInputFile[] — Metadata for files uploaded with the input, if any. - `name` string, required — The original filename. - `size_bytes` integer, required — The file size in bytes. - `parent_agent_id` string, nullable — For sub-agent invocations, the agent_id of the agent that invoked this one. Null for entry-point agents. - `parent_session_id` string, nullable — For sub-agent invocations, the session_key of the parent agent session. Null for entry-point agents. - `depth` integer — Nesting depth of this agent invocation. 0 for entry-point agents, 1 for first-level sub-agents, and so on. - `content` InvokeAgentSpanContent — The content of an invoke_agent span. - `input_messages` string — Input messages sent to the LLM. - `output_messages` string — Output messages returned by the LLM. - `thinking` string — Extended thinking content, if available. - `system_instructions` string — System instructions provided to the LLM. - object — Common properties shared by all agent trace span types. - `span_id` string, required — The unique identifier of the span. - `parent_span_id` string, nullable — The identifier of the parent span, if any. - `trace_id` string, required — The identifier of the trace this span belongs to. - `started_at` string, date-time, required — The time this span started. - `duration_ms` integer — Duration of this span in milliseconds. - `status` 'ok' | 'error', required — The status of an agent trace span. - `error_message` string, nullable — The error message when the span status is error. - `step_name` string, nullable — The name of the agent step active when this span was created. - `has_children` boolean, required — Whether this span has child spans. - `operation` string, required — The operation type for this span. - `attributes` ChatSpanAttributes — Attributes for a chat (LLM completion) span. - `model` string — The LLM model used for this completion. - `input_tokens` integer — Number of input tokens in this completion. - `output_tokens` integer — Number of output tokens in this completion. - `cache_read_input_tokens` integer — Number of input tokens read from cache. - `finish_reasons` string[] — The reasons the LLM generation finished, one per returned completion. Typically a single-element array (e.g., `["stop"]`), but providers may return multiple entries when batching completions. - `temperature` number, double — The temperature parameter used for generation. - `max_tokens` integer — The maximum tokens parameter used for generation. - `provider_name` string — The LLM provider name. - `response_id` string — The provider response identifier. - object — Common properties shared by all agent trace span types. - `span_id` string, required — The unique identifier of the span. - `parent_span_id` string, nullable — The identifier of the parent span, if any. - `trace_id` string, required — The identifier of the trace this span belongs to. - `started_at` string, date-time, required — The time this span started. - `duration_ms` integer — Duration of this span in milliseconds. - `status` 'ok' | 'error', required — The status of an agent trace span. - `error_message` string, nullable — The error message when the span status is error. - `step_name` string, nullable — The name of the agent step active when this span was created. - `has_children` boolean, required — Whether this span has child spans. - `operation` string, required — The operation type for this span. - `attributes` ExecuteToolSpanAttributes — Attributes for an execute_tool span. - `tool_name` string — The name of the tool called. - `tool_key` string — The configuration key of the tool called. - `tool_call_id` string — The LLM-assigned tool call identifier. - `tool_type` string — The type of the tool (e.g. corpora_search, web_search). - `tool_input_event_id` string — The event ID for the tool input. - `tool_output_event_id` string — The event ID for the tool output. - `corpus_keys` string[] — Corpus keys accessed by the tool. - `content` ExecuteToolSpanContent — The content of an execute_tool span. - `tool_arguments` string — Arguments passed to the tool call. - `tool_result` string — Result returned by the tool call. - object — Common properties shared by all agent trace span types. - `span_id` string, required — The unique identifier of the span. - `parent_span_id` string, nullable — The identifier of the parent span, if any. - `trace_id` string, required — The identifier of the trace this span belongs to. - `started_at` string, date-time, required — The time this span started. - `duration_ms` integer — Duration of this span in milliseconds. - `status` 'ok' | 'error', required — The status of an agent trace span. - `error_message` string, nullable — The error message when the span status is error. - `step_name` string, nullable — The name of the agent step active when this span was created. - `has_children` boolean, required — Whether this span has child spans. - `operation` string, required — The operation type for this span. - `content` ThinkingSpanContent — The content of a thinking span. - `thinking` string — Extended thinking content. - object — Common properties shared by all agent trace span types. - `span_id` string, required — The unique identifier of the span. - `parent_span_id` string, nullable — The identifier of the parent span, if any. - `trace_id` string, required — The identifier of the trace this span belongs to. - `started_at` string, date-time, required — The time this span started. - `duration_ms` integer — Duration of this span in milliseconds. - `status` 'ok' | 'error', required — The status of an agent trace span. - `error_message` string, nullable — The error message when the span status is error. - `step_name` string, nullable — The name of the agent step active when this span was created. - `has_children` boolean, required — Whether this span has child spans. - `operation` string, required — The operation type for this span. - `event_id` string, required — The session event that produced this span. - `content` OutputSpanContent — The content of an output span. - `output_text` string — The text output produced by the agent. - object — Common properties shared by all agent trace span types. - `span_id` string, required — The unique identifier of the span. - `parent_span_id` string, nullable — The identifier of the parent span, if any. - `trace_id` string, required — The identifier of the trace this span belongs to. - `started_at` string, date-time, required — The time this span started. - `duration_ms` integer — Duration of this span in milliseconds. - `status` 'ok' | 'error', required — The status of an agent trace span. - `error_message` string, nullable — The error message when the span status is error. - `step_name` string, nullable — The name of the agent step active when this span was created. - `has_children` boolean, required — Whether this span has child spans. - `operation` string, required — The operation type for this span. - `event_id` string, required — The session event that produced this span. - `attributes` StepTransitionSpanAttributes — Attributes for a step_transition span. - `from_step` string — The name of the step the agent transitions from. - `to_step` string — The name of the step the agent transitions to. - object — Common properties shared by all agent trace span types. - `span_id` string, required — The unique identifier of the span. - `parent_span_id` string, nullable — The identifier of the parent span, if any. - `trace_id` string, required — The identifier of the trace this span belongs to. - `started_at` string, date-time, required — The time this span started. - `duration_ms` integer — Duration of this span in milliseconds. - `status` 'ok' | 'error', required — The status of an agent trace span. - `error_message` string, nullable — The error message when the span status is error. - `step_name` string, nullable — The name of the agent step active when this span was created. - `has_children` boolean, required — Whether this span has child spans. - `operation` string, required — The operation type for this span. - `event_id` string, required — The session event that produced this span. - `attributes` ImageReadSpanAttributes — Attributes for an image_read span. - `artifact_id` string — The ID of the loaded image artifact. - `detail` string — The detail level used for image processing. - object — Common properties shared by all agent trace span types. - `span_id` string, required — The unique identifier of the span. - `parent_span_id` string, nullable — The identifier of the parent span, if any. - `trace_id` string, required — The identifier of the trace this span belongs to. - `started_at` string, date-time, required — The time this span started. - `duration_ms` integer — Duration of this span in milliseconds. - `status` 'ok' | 'error', required — The status of an agent trace span. - `error_message` string, nullable — The error message when the span status is error. - `step_name` string, nullable — The name of the agent step active when this span was created. - `has_children` boolean, required — Whether this span has child spans. - `operation` string, required — The operation type for this span. - `event_id` string, required — The session event that produced this span. - `attributes` CompactionSpanAttributes — Attributes for a compaction span. - `turns_compacted` integer — Number of conversation turns compacted. - `events_compacted` integer — Number of events hidden by compaction. - `summary_key` string — Key of the summary created by compaction. - `metadata` ListMetadata — The standard metadata in the response of a list operation. - `page_key` string — The page key for the next page of results. Pass it as a query parameter to request the next page. ## Other responses - `403` — Permissions do not allow accessing this trace. - `404` — Trace not found. --- [API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/fca567a46b3a/schema)