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.
{
"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_kmust 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:
{
"error": "invalid_trace",
"issues": [{ "path": ["retrieval"], "message": "Invalid input: expected object, received undefined" }]
}To check a trace before sending it:
import { validateTrace } from "@chunktrace/sdk";
const result = validateTrace(JSON.parse(text));
if (!result.ok) console.error(result.issues);