Steps API

Append steps to an existing trace incrementally. Useful for long-running runs or when steps span process boundaries.

POST /v1/traces/:id/steps

Send NDJSON-encoded step records. Each line is a complete step. The server validates each line independently and returns per-line status.

POST /v1/traces/tr_…/steps
x-api-key: tk_live_…
Content-Type: application/x-ndjson

{"name":"plan","type":"llm","model":"claude-sonnet-4-6","messages":[…]}
{"name":"kb.search","type":"retrieval","metadata":{"doc_count":8}}
{"name":"draft","type":"llm","model":"claude-sonnet-4-6","messages":[…]}

Notes

Steps cannot reference a trace ID that doesn't exist yet.
Parent step IDs are optional; if omitted, the API parents in arrival order.
Idempotency: include idempotency_key per step to make retries safe.

← Traces

Media →