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
Query Parameters
Filter by platform label. Folded like the stored value (trimmed, lowercased), so
?framework=LangChain matches traces stored as "langchain"."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:
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).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"
}

