> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Traces

> Search traces using query parameters on the List Traces endpoint.

Trace search is performed via query parameters on the [List Traces](/api-reference/traces/overview) endpoint.

## Query Parameters

All filters are optional. Passing an empty string (e.g. `?agent_name=`) returns `400` rather than silently matching everything — omit the param entirely for "no filter". Unknown enum values return `422`.

### Core filters

| Parameter         | Type       | Description                                                                                                                                                |
| ----------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search`          | `string`   | Full-text search across user input, final output, and agent name                                                                                           |
| `agent_name`      | `string`   | Filter by agent name                                                                                                                                       |
| `status`          | `string`   | Trace status: `success`, `error`, or `degraded`                                                                                                            |
| `eval_verdict`    | `string`   | Eval verdict: `pass`, `fail`, `keep`, `drop`, `review` (open-string), or `unevaluated` for traces with no verdict yet                                      |
| `source_type`     | `string`   | How the trace was produced: `production`, `test`, `evaluation`, `sdk`, `manual`, `synthetic`, `development`, `sandbox`, `eval_replay`, `sample`, `demo`, … |
| `started_at_from` | `datetime` | Inclusive lower bound on `started_at` (ISO 8601). Malformed dates return `422`                                                                             |
| `started_at_to`   | `datetime` | Inclusive upper bound on `started_at` (ISO 8601)                                                                                                           |

### Manifest & compatibility

| Parameter            | Type     | Description                                                                                           |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `manifest_id`        | `string` | Filter by the manifest hash that produced the trace                                                   |
| `target_manifest_id` | `string` | Score each trace's compatibility against this manifest (enriches results with a `compat` object)      |
| `compat_status`      | `string` | Keep only traces with this compat verdict vs `target_manifest_id`: `keep`, `repair`, `replay`, `drop` |

### Multi-agent, tools & skills

| Parameter          | Type     | Description                                                                                   |
| ------------------ | -------- | --------------------------------------------------------------------------------------------- |
| `tool_name`        | `string` | Traces that invoked the named tool                                                            |
| `skill_name`       | `string` | Traces where the named skill was activated                                                    |
| `child_agent_name` | `string` | Parent traces whose child agent matches this name                                             |
| `child_status`     | `string` | Further filter child matches by status: `success`, `error`, `degraded`                        |
| `has_spans`        | `bool`   | `true` excludes traces with zero spans; `false` returns only empty-span traces; omit for both |
| `has_llm_calls`    | `bool`   | Symmetric filter for traces with zero LLM calls                                               |

### Paging & sort

| Parameter | Type     | Description                                                                             |
| --------- | -------- | --------------------------------------------------------------------------------------- |
| `limit`   | `int`    | Page size, 1–100 (default 20)                                                           |
| `offset`  | `int`    | Number of rows to skip (default 0)                                                      |
| `sort`    | `string` | Order by `created_at` or `started_at`; prefix `-` for descending. Default `-created_at` |

<Note>
  There is no numeric eval-score range filter on this endpoint. Filter by the
  categorical `eval_verdict` instead, then read each trace's `eval_score` from
  the response.
</Note>

## Example

```bash theme={null}
curl "https://api.decimal.ai/api/v1/traces?agent_name=my-agent&eval_verdict=drop&limit=20" \
  -H "Authorization: Bearer dai_sk_..."
```