Generation traces v0.2+

Endpoint

POST /v1/generation-traces

Request body

JSON object with a single events array. Each event is idempotent on (organization_id, clientEventId).

events array required

One to 50 events per batch. The cap is lower than retrieval-traces because output payloads can be much larger.

events[].clientEventId string required

UUIDv7-style identifier. Max 128 chars.

events[].output object required

{ text?: string }. Send text when capturing plaintext or redacted output. Omit on error paths. Max 32,000 characters.

events[].latencyMs integer required

LLM call latency in milliseconds, non-negative, max 600,000 (10 min).

events[].timestamp iso8601 required

Client-side timestamp of the LLM call.

events[].sdk object required

{ lang: 'ts' | 'python', version: string }.

events[].runId string

Strongly recommended. Correlation anchor. When this value matches a prior retrieval's parentQueryId, the matcher attributes the generation's content to that retrieval's vectors. Without it, no citations will be written. LangChain users get this for free. Max 128 chars.

events[].parentRunId string

Secondary correlation anchor — matched the same way as runId. Use it when your run tree nests one level deeper than the retriever's parent (e.g. LCEL chains where the LLM step sits alongside the retriever under a common root). Max 128 chars.

events[].collectionId, agentId, model, promptTokens, completionTokens, error, metadata

Optional. Used to enrich the trace and for analytics.

How correlation works

When a generation is ingested, Buzo finds recent retrieval traces whose parentQueryId matches this generation's runId or parentRunId, loads the content it already stores for each returned vector, and runs a tiered content match against output.text — verbatim substring first, n-gram similarity as a fallback for paraphrase.

Hits on a currently-quarantined vector enqueue a CITED_FLAGGED alert and append to the tamper-evident audit chain.

Response