curl "http://localhost:4700/api/v1/ingest/traces?limit=20&source=production&framework=langchain" \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8"
{
"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"
}
Tracing
List Traces
Cursor-paginated list of ingested traces with database-side search and filters
GET
/
api
/
v1
/
ingest
/
traces
curl "http://localhost:4700/api/v1/ingest/traces?limit=20&source=production&framework=langchain" \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8"
{
"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"
}
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 or OpenTelemetry.
Authentication
string
required
Project API key.
Query Parameters
number
default:"50"
Page size, 1 to 100.
string
Trace
_id to continue after, taken from nextCursor in the previous response.string
Filter by platform label. Folded like the stored value (trimmed, lowercased), so
?framework=LangChain matches traces stored as "langchain".string
Database-side text search over the trace list.
string
default:"all"
"production" (excludes eval-run traffic), "eval" (eval-run traffic only), or "all".
The dashboard’s Live Traces sends "production" by default.Response
number
Total root traces matching the filters across all pages - what the dashboard’s pagination
range (“1-50 of N”) is computed from.
array
Array of trace objects, newest first. Each has:
Optional fields are omitted, not
| 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 |
null (except the two token counts and judgeScores, which are always
present and nullable).boolean
Whether more traces exist after this page.
string | null
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, addingmetadata,performanceSummary,cacheReadTokens/cacheWriteTokens,estimatedCostUSD(null when the model has no catalog pricing or the trace has no token counts), andtopic(intent/sentiment/issue classification, when topics ran).404if 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
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 }
curl "http://localhost:4700/api/v1/ingest/traces?limit=20&source=production&framework=langchain" \
-H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8"
{
"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"
}