---
title: "List agent traces"
method: GET
path: "/v2/agent_analytics/traces"
tags: ["Agent Analytics"]
---

# List agent traces

`GET /v2/agent_analytics/traces`

Lists agent traces with optional filtering by agent, session, status, and time range.

## Query parameters

- `agent_key` string
- `session_key` string
- `status` 'ok' | 'error'
- `error_type` 'context_limit_exceeded' | 'step_transition_limit_exceeded' | 'actions_limit_reached' | 'llm_generation_error' | 'stream_error' | 'internal'
- `operation` 'invoke_agent' | 'chat' | 'execute_tool' | 'thinking' | 'output' | 'step_transition' | 'image_read' | 'compaction'
- `tool_name` string
- `tool_error_type` 'invalid_input' | 'not_found' | 'forbidden' | 'invalid_configuration' | 'timeout' | 'execution_error' | 'dependency_failed'
- `started_after` string, date-time
- `started_before` string, date-time
- `min_duration_ms` integer
- `max_duration_ms` integer
- `limit` integer
- `page_key` string

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Response `200`

List of agent traces.

- ListAgentTracesResponse — A list of agent traces.
  - `traces` AgentTrace[], required — The list of agent traces.
    - `trace_id` string, required — The unique identifier of the trace.
    - `agent_key` string — A unique key that identifies an agent.
    - `session_key` string — A unique key that identifies an agent session.
    - `started_at` string, date-time, required — The time the trace started.
    - `duration_ms` integer — Total duration of the trace in milliseconds.
    - `status` 'ok' | 'error', required — The final status of the trace.
    - `input_tokens` integer — Total input tokens consumed across all spans.
    - `output_tokens` integer — Total output tokens produced across all spans.
  - `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 listing traces.

---

[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/83554494d7f8/schema)