Ingest a trace
Ingest a single trace from the SDK.
Data Model
A trace contains two types of children:
spansβ represent operations (agent steps, tool calls, chains). Nest viaparent_span_idto form a tree.llm_callsβ represent individual LLM invocations with full fidelity (model, tokens, messages, response). Link to a parent span viaspan_id.
Structuring Rules
Spans should be used for containers and non-LLM operations:
span_type | Use for | Example |
|---|---|---|
agent | Top-level agent invocation (root span) | finance-research-agent |
tool | Tool/function execution | get_stock_price |
chain | Multi-step pipeline or sub-chain | research-pipeline |
retrieval | RAG retrieval step | vector-search |
llm | Wrapper span for an LLM call (optional) | LLM: plan step 1 |
LLM calls should be used for every LLM invocation:
- Always set
span_idto the parent span that triggered this call - Include
rendered_input(list of messages),output,model_name,provider - Include
started_at/ended_atfor timeline visualization - Include token counts (
input_tokens,output_tokens) for cost tracking
Tree Rendering
The frontend builds a unified tree from both tables:
- If an
llm_callhasspan_idmatching a span β it enriches that span (shown as one node with LLM details in a tab) - If an
llm_callhas no matching span β shown as a standalone π§ node under the root span - All children are sorted by
started_atfor chronological order
Example Structure
agent-step (span, type=agent)
βββ llm_call_1 (llm_call, span_id=agent-step)
βββ tool-span (span, type=tool, parent_span_id=agent-step)
βββ llm_call_2 (llm_call, span_id=agent-step)
Returns 409 if a trace with the same ID already exists.
Partial success
The trace row itself is written first; the enrichment stages that follow
(built-in evals, SDK eval scores, skill activations, manifest inference,
parent propagation) are individually guarded so one broken stage cannot
drop the trace. If any of them fails, the response is 207 Multi-Status
with status="partial" and failed_stages=[...] naming the stages whose
writes did not land β the trace ID is still returned and is still valid.
Treat 207 as βstored, but do not trust the derived data for this traceβ.
Authorizations
Enter your API key (e.g. dai_sk_test_key_001)
Headers
Cookies
Body
The body is of type Payload Β· object.
Response
Ingestion result with counts
The response is of type Response Ingest Trace Api V1 Traces Post Β· object.