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

# Search and inspect Armature workflow runs over REST

> Search runs by workflow, status, or classification and pull traces, evaluation evidence, and tool-call history into your own dashboards or pipelines.

The `/runs` endpoints expose Armature's workflow run history. Use them to pipe run results into BI tools, gate deploys on workflow status from CI, or build custom dashboards on top of the same evidence the Armature UI uses.

All paths are relative to the [REST API base URL](/rest-api/overview#base-url). All requests require an [API key](/rest-api/authentication). Run data is redacted using the same policy as the dashboard and MCP API.

## Search runs

```http theme={null}
GET /runs
```

Returns a paginated list of runs matching the supplied filters.

**Query parameters**

| Parameter          | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| `range`            | Time range — `24h`, `7d`, or `30d`. Defaults to `24h`.        |
| `workflowId`       | Filter to one workflow.                                       |
| `status`           | Filter by run status — for example `pass`, `fail`, `running`. |
| `classification`   | Filter by evaluation classification.                          |
| `search`           | Free-text search across run metadata.                         |
| `page`, `pageSize` | Pagination controls.                                          |
| `sort`             | Sort key.                                                     |

```bash theme={null}
curl "https://your-org.armature.app/api/armature/v1/runs?workflowId=wf_…&status=fail&range=7d" \
  -H "Authorization: Bearer amt_<key-id>_<secret>"
```

## Get a single run

```http theme={null}
GET /runs/{id}
```

Returns the run summary — workflow, status, start and end timestamps, model, evaluator output, and cost.

```bash theme={null}
curl https://your-org.armature.app/api/armature/v1/runs/{id} \
  -H "Authorization: Bearer amt_<key-id>_<secret>"
```

## Get the run trace

```http theme={null}
GET /runs/{id}/trace
```

Returns the redacted trace, including spans and tool calls that the tester agent emitted during the run. This is the same trace shown in the dashboard's run detail view.

## Get the run evaluation

```http theme={null}
GET /runs/{id}/evaluation
```

Returns the evaluation evidence: per-criterion results, the judge model's verdict, and the supporting excerpts.

## List run tool calls

```http theme={null}
GET /runs/{id}/tool-calls
```

Returns the recorded MCP tool calls for the run as a list of rows, each with the tool name, arguments, result body, and duration.

```bash theme={null}
curl https://your-org.armature.app/api/armature/v1/runs/{id}/tool-calls \
  -H "Authorization: Bearer amt_<key-id>_<secret>"
```

## Typical polling loop

After dispatching a workflow with [`POST /workflows/{id}/runs`](/rest-api/workflows#manually-dispatch-a-run), poll the run until it reaches a terminal state, then fetch the evaluation:

```bash theme={null}
# Poll status
curl https://your-org.armature.app/api/armature/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $ARMATURE_API_KEY"

# Once status is terminal (pass, fail, partial), fetch the evaluation
curl https://your-org.armature.app/api/armature/v1/runs/$RUN_ID/evaluation \
  -H "Authorization: Bearer $ARMATURE_API_KEY"
```

## Related

* [Workflow runs in the dashboard](/workflows/runs) — UI view of the same data.
* [Dispatch a workflow](/rest-api/workflows#manually-dispatch-a-run) — kick off the runs you then inspect here.