Reference
HTTP API
Send traces and read diagnoses over HTTPS. The SDK uses this API; so can anything else that speaks JSON.
Basics#
The API lives at:
https://api.chunktrace.comSend your API key as a bearer token on every request:
curl https://api.chunktrace.com/v0/me \
-H "authorization: Bearer $CHUNKTRACE_KEY"A key belongs to one project and sees only that project's traces. A full-access key can do everything here. A read-only key can make GET requests only. Create keys in the dashboard under Settings.
Requests and responses are JSON.
Send traces#
POST /v0/tracesThe body is one trace, or an array of up to 100. See Trace schema for the shape.
curl -X POST https://api.chunktrace.com/v0/traces \
-H "authorization: Bearer $CHUNKTRACE_KEY" \
-H "content-type: application/json" \
--data @trace.json{ "trace_id": "tr_mwk0ppb3_unefr7", "status": "accepted" }| Status | Meaning |
|---|---|
202 |
Accepted. The trace is queued and is diagnosed within moments. |
200 |
Every trace in the request was already stored ("status": "duplicate"). Nothing changed. |
400 |
The body is not valid. issues lists each problem with its path. |
413 |
The body is larger than 1 MB. |
A trace_id is unique within a project, so sending a trace again is safe: it is stored once and diagnosed once.
A batch returns { "results": [ … ] } with one entry per trace. If any trace in a batch is invalid, none are stored, and invalid lists the bad ones by index.
Get a trace#
GET /v0/traces/:id{
"trace_id": "tr_mwk0ppb3_unefr7",
"received_at": "2026-11-17T01:32:47.620Z",
"status": "diagnosed",
"primary_code": "TOPK_CUT",
"engine_version": 1,
"diagnosed_at": "2026-11-17T01:32:47.625Z",
"trace": { "…": "the trace as you sent it" },
"diagnosis": { "findings": [ … ], "summary": { … } }
}status is queued, diagnosed or failed. diagnosis.findings is the list described in Finding codes.
Its timeline#
GET /v0/traces/:id/timelineThe stage-by-stage view the dashboard draws: for each of the seven stages, how many chunks went in and out, which were kept and dropped, and why.
List traces#
GET /v0/tracesNewest first.
| Parameter | What it does |
|---|---|
limit |
Traces per page, 1 to 200. Default 50. |
before |
Return traces received before this time. Pass the previous page's next_before. |
offset |
Skip this many, for numbered pages. |
primary_code |
Only traces with this primary finding, e.g. TOPK_CUT. |
app, env |
Only traces from this app name or environment. |
answer_correct |
true or false. |
since, until |
Only traces received in this time range (ISO 8601). |
q |
Only traces whose query contains this text. |
{
"items": [
{
"trace_id": "tr_mwk0ppb3_unefr7",
"received_at": "2026-11-17T01:32:47.620Z",
"status": "diagnosed",
"app": { "name": "quickstart" },
"query": "How many days do I have to request a refund?",
"primary_code": "TOPK_CUT",
"answer_correct": false
}
],
"total": 51,
"next_before": "2026-11-17T01:31:20.119Z"
}total counts every trace that matches the filters. next_before is null on the last page.
Stats#
GET /v0/statsCounts for the project, optionally within since and until:
{
"traces": { "total": 150, "queued": 0, "diagnosed": 150, "failed": 0 },
"by_primary_code": { "EVIDENCE_IN_CONTEXT": 75, "TOPK_CUT": 51, "THRESHOLD_REMOVED": 8 },
"answer_correct": { "true": 71, "false": 79, "unknown": 0 },
"apps": { "support-bot": 148, "quickstart": 2 },
"envs": { "prod": 115, "staging": 33 },
"engine_version": 1
}GET /v0/stats/timeseries?bucket=day&tz=Europe/BerlinTraces per hour or day in the time zone you name, each split into correct, wrong and unknown.
Keys#
| Request | What it does |
|---|---|
GET /v0/me |
The key you are using: its name, scope and project. |
GET /v0/keys |
The project's keys. Secrets are never returned. |
POST /v0/keys |
Create a key: { "name": "ci", "scope": "read" }. The secret is in the response, once. |
DELETE /v0/keys/:id |
Revoke a key. |
Creating and revoking need a full-access key.
Errors#
Errors are JSON with an error code and, usually, a message:
{ "error": "forbidden", "message": "this key is read-only" }| Status | error |
Meaning |
|---|---|---|
400 |
invalid_trace, invalid_json, batch_too_large |
The request body is wrong. |
401 |
unauthorized |
The key is missing, wrong or revoked. |
403 |
forbidden |
A read-only key tried to write. |
404 |
not_found |
No such trace in this project. |
413 |
payload_too_large |
The body is over 1 MB. |