Python SDK

import decimalai

# Auto-instrumentation (recommended)
decimalai.init(api_key="dai_sk_...", openai_agents=True)

# Or manual tracing with decorator
@decimalai.trace(agent_name="my-agent")
def run_agent(query: str) -> str:
    return llm.invoke(query)

run_agent("What is the weather?")

{
  "status": "ok",
  "id": "trc_abc123",
  "trace_id": "trc_abc123",
  "agent_name": "my-agent",
  "spans": 5,
  "llm_calls": 3
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

traces

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 via parent_span_id to form a tree.
llm_calls — represent individual LLM invocations with full fidelity (model, tokens, messages, response). Link to a parent span via span_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_id to the parent span that triggered this call
Include rendered_input (list of messages), output, model_name, provider
Include started_at/ended_at for 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_call has span_id matching a span → it enriches that span (shown as one node with LLM details in a tab)
If an llm_call has no matching span → shown as a standalone 🧠 node under the root span
All children are sorted by started_at for 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.

POST

api

traces

Python SDK

import decimalai

# Auto-instrumentation (recommended)
decimalai.init(api_key="dai_sk_...", openai_agents=True)

# Or manual tracing with decorator
@decimalai.trace(agent_name="my-agent")
def run_agent(query: str) -> str:
    return llm.invoke(query)

run_agent("What is the weather?")

{
  "status": "ok",
  "id": "trc_abc123",
  "trace_id": "trc_abc123",
  "agent_name": "my-agent",
  "spans": 5,
  "llm_calls": 3
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Enter your API key (e.g. dai_sk_test_key_001)

Headers

Authorization

string

Cookies

decimal_session

string | null

Body

application/json

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.

List traces Ingest a batch of traces