Skip to content

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:

Base URL
https://api.chunktrace.com

Send your API key as a bearer token on every request:

Terminal
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#

Request
POST /v0/traces

The body is one trace, or an array of up to 100. See Trace schema for the shape.

Terminal
curl -X POST https://api.chunktrace.com/v0/traces \
  -H "authorization: Bearer $CHUNKTRACE_KEY" \
  -H "content-type: application/json" \
  --data @trace.json
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#

Request
GET /v0/traces/:id
JSON
{
  "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#

Request
GET /v0/traces/:id/timeline

The 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#

Request
GET /v0/traces

Newest 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.
JSON
{
  "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#

Request
GET /v0/stats

Counts for the project, optionally within since and until:

JSON
{
  "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
}
Request
GET /v0/stats/timeseries?bucket=day&tz=Europe/Berlin

Traces 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:

JSON
{ "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.