Traces API

A trace is one complete agent run: its input, LLM calls, tool calls and output. Evaluations, regression checks and datasets all read traces. The SDK sends them for you: give your agent its framework’s agent_config(). To read one, see Read a run. Scores and verdicts are on Evaluations.

Endpoints

Route	What it does
`POST /api/v1/traces`	Send one trace. `agent_name` and `manifest_id` are required: see the manifest handshake. Answers 409 if the id already exists
`POST /api/v1/traces/batch`	Send several
`POST /api/v1/traces/import-bulk`	Send historical traces. A duplicate id is skipped, so re-running is safe
`POST /api/v1/traces/import`	Upload a JSONL file
`GET /api/v1/traces`	List and search
`GET /api/v1/traces/{trace_id}`	One trace with its spans and LLM calls. `?include=eval_scores` adds its scores
`GET /api/v1/traces/stats`, `/traces/eval/stats`	Totals across traces, and eval rollups

Search traces

Search is GET /api/v1/traces with query parameters: there’s no separate search route. Every filter is optional. ?agent_name= with an empty value answers 400 rather than matching everything, so leave out a filter you don’t want. An unknown status, source_type, child_status, prompt_source, experiment_arm or sort answers 422.

curl "https://api.decimal.ai/api/v1/traces?agent_name=my-agent&eval_verdict=fail&limit=20" \
  -H "Authorization: Bearer $DECIMAL_API_KEY"

It returns traces, total, limit, offset and target_manifest_id.

Core filters

Parameter	What it matches
`search`	Text in the user input, final output or agent name
`agent_name`	The agent
`status`	`success`, `error` or `degraded`
`eval_verdict`	`pass`, `fail` or `review`. `unevaluated` means no verdict yet, and `evaluated` means any verdict
`source_type`	`production`, `test`, `evaluation`, `sdk`, `manual`, `synthetic`, `development`, `sandbox`, `distillation`, `snapshot`, `file`, `url`, `eval_replay`, `sample`, `demo` or `hosted_trial`
`started_at_from`, `started_at_to`	An inclusive range on `started_at`, in ISO 8601
`include_fixtures`	`false` drops DecimalAI’s own test agents from a broad listing. Default `true`, and ignored when you filter by agent, child agent, tool or skill

There’s no filter on a numeric score. Filter on eval_verdict, then read each trace’s eval_score.

Prompts and experiments

Parameter	What it matches
`prompt_version`	Runs on this saved prompt version. Each listed trace carries its record as `prompt`
`prompt_source`	`fallback`: runs on the `fallback=` prompt in the code, because DecimalAI couldn’t be reached or had none saved
`experiment`	Runs this experiment put in a group. Each listed trace carries its group as `experiment`
`experiment_arm`	One group: `held_out` or `with` for a skill holdout, `a` or `b` for a prompt split. Answers 400 without `experiment`

Manifests and training verdicts

Parameter	What it does
`manifest_id`	Traces from this manifest
`target_manifest_id`	Adds a `compat` object to each trace, scored against this manifest, and leaves out traces created after the next manifest
`compat_status`	The training verdict: `keep`, `repair`, `replay` or `drop`. With `target_manifest_id`, the verdict against that manifest, with no time limit. Without it, the verdict stored on the trace

Multi-agent, tools and skills

Parameter	What it matches
`tool_name`	Traces that called this tool
`skill_name`	Traces where this skill was Loaded
`child_agent_name`	Parent traces with a child agent of this name
`child_status`	With `child_agent_name`, children with this status
`has_spans`	`true`: at least one span. `false`: none
`has_llm_calls`	The same, for LLM calls

Paging and order

Parameter	What it does
`limit`	Page size, 1 to 100. Default 20
`offset`	Rows to skip. Default 0
`sort`	`created_at` or `started_at`, with `-` for descending. Default `-created_at`

Structure

A trace has two kinds of children:

Type	What it represents
Spans	Containers and non-LLM steps, such as an agent step, a tool call or a retrieval. They nest with `parent_span_id`
LLM calls	One model call each: prompt, completion, tokens and latency. `span_id` links one to its parent span

Python SDK

Skills in your repo

CLI

REST

Endpoints

Search traces

Core filters

Prompts and experiments

Manifests and training verdicts

Multi-agent, tools and skills

Paging and order

Structure

​Endpoints

​Search traces

​Core filters

​Prompts and experiments

​Manifests and training verdicts

​Multi-agent, tools and skills

​Paging and order

​Structure

Endpoints

Search traces

Core filters

Prompts and experiments

Manifests and training verdicts

Multi-agent, tools and skills

Paging and order

Structure