Skip to content

Reference

Trace schema

The JSON a trace is made of. The SDK builds it for you; build it yourself to send traces from any language.

A trace#

One trace describes one query: what was asked, what retrieval returned, what was reranked, what went into the prompt, and what came out.

trace.json
{
  "schema_version": "0",
  "trace_id": "tr_mwk0ppb3_unefr7",
  "timestamp": "2026-11-17T01:32:47.583Z",
  "app": { "name": "support-bot", "env": "prod" },
  "query": { "text": "How many days do I have to request a refund?" },
  "label": { "type": "keyword", "values": ["30 days"] },
  "retrieval": {
    "index": { "name": "support-docs", "provider": "pgvector" },
    "params": { "top_k": 1, "metadata_filter": { "tenant": "acme" } },
    "candidates": [
      { "chunk_id": "faq#3", "rank": 1, "score": 0.61, "matches_label": false }
    ],
    "shadow": {
      "top_k": 50,
      "candidates": [
        { "chunk_id": "faq#3", "rank": 1, "score": 0.61, "metadata": { "tenant": "acme" }, "matches_label": false },
        { "chunk_id": "refund-policy#2", "rank": 2, "score": 0.498, "metadata": { "tenant": "acme" }, "matches_label": true }
      ]
    }
  },
  "context": {
    "included": [{ "chunk_id": "faq#3", "order": 1, "token_count": 17 }],
    "excluded": []
  },
  "generation": { "model": "gpt-4.1-mini", "answer": "I don't have that information.", "answer_correct": false }
}

Top level#

Field Required Notes
schema_version yes Always "0".
trace_id yes 1 to 256 characters. Unique within your project.
timestamp yes When the query ran, ISO 8601 with a time zone.
app no name, env, version. All optional strings.
query.text yes The question.
label no What a right answer should cite. See Labels.
retrieval yes What the search returned.
rerank no What the reranker did.
context yes What went into the prompt.
generation no model, answer, answer_correct.

retrieval#

Field Required Notes
index.name yes The index or collection searched. index.provider is optional.
params.top_k yes A positive integer.
params.similarity_threshold no A number.
params.metadata_filter no See metadata filters.
candidates yes The chunks your search returned, in rank order.
shadow no { top_k, candidates } from an unfiltered search. See Diagnose mode.

A candidate#

Field Required Notes
chunk_id yes
rank yes 1 is best.
score yes Similarity. Higher is better.
document_id no Needed for document labels.
token_count no
metadata no Keys to strings, numbers, booleans or null. Send at least the keys your filter uses.
matches_label no Whether this chunk matches the label. If you leave it out, the server matches document labels by document_id and keyword labels against text.
text no The chunk's text. Only needed if you want the server to match keyword labels.

rerank#

Field Required Notes
model, top_n, score_threshold no The reranker and its limits.
results yes One entry per chunk: chunk_id, rank_before, rank_after, score, kept.

context#

Field Required Notes
token_budget no
included yes Chunks in the prompt: chunk_id, order (1 is first), optional token_count.
excluded yes Chunks left out: chunk_id, reason, optional detail. reason is token_budget, dedupe, max_chunks or custom.

Validation#

The server checks every trace against this schema.

  • Fields it doesn't know are dropped, not rejected.
  • Scores and ranks must be numbers; ranks and top_k must be positive integers.
  • A trace that passes can always be diagnosed.

A trace that fails comes back as 400 with the path and reason for each problem:

JSON
{
  "error": "invalid_trace",
  "issues": [{ "path": ["retrieval"], "message": "Invalid input: expected object, received undefined" }]
}

To check a trace before sending it:

JavaScript
import { validateTrace } from "@chunktrace/sdk";

const result = validateTrace(JSON.parse(text));
if (!result.ok) console.error(result.issues);