> ## Documentation Index
> Fetch the complete documentation index at: https://developers.agentx.so/llms.txt
> Use this file to discover all available pages before exploring further.
# List Traces
> Cursor-paginated list of ingested traces with database-side search and filters
Returns the project's root traces, newest first, with cursor-based pagination. This is what the
dashboard's Live Traces feed (Observe) reads; use it to browse or export what your
agents ingested via [Submit Trace](/api-reference/tracing/submit-trace) or OpenTelemetry.
## Authentication
Project API key.
## Query Parameters
Page size, 1 to 100.
Trace `_id` to continue after, taken from `nextCursor` in the previous response.
Filter by platform label. Folded like the stored value (trimmed, lowercased), so
`?framework=LangChain` matches traces stored as `"langchain"`.
Database-side text search over the trace list.
`"production"` (excludes eval-run traffic), `"eval"` (eval-run traffic only), or `"all"`.
The dashboard's Live Traces sends `"production"` by default.
## Response
Total root traces matching the filters across all pages - what the dashboard's pagination
range ("1-50 of N") is computed from.
Array of trace objects, newest first. Each has:
| Field | Type | Description |
| --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id` | string | Trace ID |
| `name` | string | Agent or operation label |
| `input` | any | Agent input (omitted when absent) |
| `output` | any | Agent output (omitted when absent) |
| `latencyMs` | number | Latency in ms |
| `error` | string | Error message if the run failed |
| `framework` | string | Platform label, lowercased |
| `model` | string | LLM model |
| `toolCalls` | array | Tool calls made during the run |
| `sessionId` | string | Session grouping key |
| `spanId` | string | Client-supplied span identity, if any |
| `spanKind` | string | Always present: `"agent"`, `"llm"`, `"tool"`, `"retrieval"`, `"chain"`, `"embedding"`, `"reranker"`, `"guardrail"`, `"evaluator"`, `"prompt"`, or `"memory"` |
| `judgeScores` | object \| null | Always present, nullable: the trace's live judge/scorer-group verdict summary for the Score chip - `{ rating, threshold, scorerName, judgeCount, failingCount, verdicts }`, or `null` when nothing scored it. A scorer-group verdict entry additionally carries `isGroup: true` |
| `parentSpanId` | string | Parent span's id, for span-tree traces |
| `startedAt` | string | ISO 8601 span start, when the producer sent one |
| `trafficSource` | string | `"eval-run"` for traces produced inside an offline evaluation; absent for production |
| `source` | string | Always `"sdk"` on self-host |
| `createdAt` | string | ISO 8601 timestamp (the traffic's own time for historical imports) |
| `inputTokens` | number \| null | Input token count, from the submitted timings/usage |
| `outputTokens` | number \| null | Output token count, from the submitted timings/usage |
Optional fields are omitted, not `null` (except the two token counts and `judgeScores`, which are always
present and nullable).
Whether more traces exist after this page.
Pass as `cursor` to fetch the next page. `null` on the last page.
## Related endpoints
* `GET /api/v1/ingest/traces/{traceId}` - full single-trace detail, adding `metadata`,
`performanceSummary`, `cacheReadTokens`/`cacheWriteTokens`, `estimatedCostUSD` (null when
the model has no catalog pricing or the trace has no token counts), and `topic`
(intent/sentiment/issue classification, when topics ran). `404` if the trace doesn't exist.
* `GET /api/v1/ingest/sessions/{sessionId}/spans` - every span in one session/OTel trace as
`{ "spans": [...] }`, ordered by span start, for assembling a span tree without pagination.
## Pagination example
```http theme={null}
GET /api/v1/ingest/traces?limit=20&source=production
→ { "traces": [...], "totalCount": 143, "hasNextPage": true, "nextCursor": "mJ3vQ8pTr2LqYw6bZk9Xd" }
GET /api/v1/ingest/traces?limit=20&source=production&cursor=mJ3vQ8pTr2LqYw6bZk9Xd
→ { "traces": [...], "totalCount": 143, "hasNextPage": false, "nextCursor": null }
```
```bash cURL theme={null}
curl "http://localhost:4700/api/v1/ingest/traces?limit=20&source=production&framework=langchain" \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8"
```
```json 200 OK theme={null}
{
"totalCount": 143,
"traces": [
{
"_id": "mJ3vQ8pTr2LqYw6bZk9Xd",
"name": "customer-support-agent",
"framework": "langchain",
"model": "gpt-4o",
"input": "How do I reset my password?",
"output": "Click Forgot Password on the login page.",
"latencyMs": 1340,
"toolCalls": [
{ "name": "search_kb", "input": "password reset", "output": "...", "success": true }
],
"sessionId": "user_session_abc123",
"spanKind": "agent",
"judgeScores": null,
"source": "sdk",
"createdAt": "2026-08-27T10:30:00.000Z",
"inputTokens": 150,
"outputTokens": 45
}
],
"hasNextPage": true,
"nextCursor": "mJ3vQ8pTr2LqYw6bZk9Xd"
}
```