Traces

REST — Traces endpoints.

Method	Path	Description
POST	/api/v1/traces	Ingest one trace
POST	/api/v1/traces/batch	Ingest a batch
GET	/api/v1/traces	List
GET	/api/v1/traces/{id}	Get
PATCH	/api/v1/traces/{id}/tags	Tag

Single body

{
 "id": "trace-123",
 "name": "answer-question",
 "inputs": {...},
 "outputs": {...},
 "spans": [...]
}

Idempotency

The trace id field is the idempotency key. POSTing the same id twice within 24 hours returns the existing trace rather than creating a duplicate. After 24 hours, a re-POST with the same id is treated as a new trace.

For batch ingestion, idempotency applies per-row by trace id.

Validation

The trace payload validates against the trace JSON Schema. Validate client-side to catch shape errors before posting.

See also

• SDK: traces
• Trace JSON Schema