REST API

Retrieval traces

Ingest a batch of retrieval events — the query the user asked and the vector IDs your retriever returned.

Endpoint

HTTP

POST /v1/retrieval-traces

Request body

JSON object with a single events array. Each event is idempotent on clientEventId.

events array required

One to 100 events per batch.

events[].clientEventId string required

UUIDv7-style identifier generated by the client. Used server-side for idempotent dedup on (organization_id, clientEventId). Max 128 chars.

events[].collectionId uuid required

The Buzo collection ID this retrieval targets.

events[].query object required

One of text, hash, or embedding must be present (empty object is allowed for error-only events).

events[].results array required

Array of { id: string, score: number, content?: string } for each returned vector. Max 200 items.

content is optional (added in SDK 0.4.0). When absent, Buzo falls back to the content_snapshot stored during the most recent scan of that vector, if one exists. When present, citation matching runs against the value in the payload. Per-item cap: 16 KB — oversized chunks are rejected rather than truncated.

events[].latencyMs integer required

Retriever call latency in milliseconds, non-negative.

events[].kReturned integer required

Size of the results array. Must match results.length.

events[].timestamp iso8601 required

Client-side timestamp of the retrieval (ISO 8601 with timezone).

events[].sdk object required

{ lang: 'ts' | 'python', version: string }. Used for telemetry-aware server handling of older clients.

events[].parentQueryId string

Correlation anchor — typically the LangChain parent run id (the chain the retriever was invoked from). When a later generation event reports the same value in its runId or parentRunId, the server attributes citations between the two. Max 128 chars.

events[].agentId, embeddingModelId, cacheHit, kRequested, resultsRerankedScores, error, metadata

Optional. See the SDK reference for their semantics and limits.

Response

Field	Type	Description
`accepted`	integer	Rows newly inserted (not duplicates).
`duplicates`	integer	Events that collided with an existing `(org, clientEventId)` — silently skipped.

Request

curl -X POST https://api.buzo.ai/v1/retrieval-traces \
  -H "Authorization: Bearer $BUZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "clientEventId": "01913e1f-3a40-7b2c-8d4f-aaaa00000001",
      "collectionId": "00000000-0000-0000-0000-000000000001",
      "query": { "text": "how do I reset my password?" },
      "results": [
        { "id": "vec_abc", "score": 0.87, "content": "Password reset links expire 24 hours after they are issued." },
        { "id": "vec_def", "score": 0.81 }
      ],
      "kReturned": 2,
      "latencyMs": 47,
      "parentQueryId": "chain-run-root",
      "timestamp": "2026-04-18T14:22:17.123Z",
      "sdk": { "lang": "ts", "version": "0.4.0" }
    }]
  }'

Response200 OK

{
  "accepted": 1,
  "duplicates": 0
}