Skip to main content
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. All requests require an API key. Run data is redacted using the same policy as the dashboard and MCP API.

​
Search runs

GET /runs
Returns a paginated list of runs matching the supplied filters. Query parameters
ParameterDescription
rangeTime range — 24h, 7d, or 30d. Defaults to 24h.
workflowIdFilter to one workflow.
statusFilter by run status — for example pass, fail, running.
classificationFilter by evaluation classification.
searchFree-text search across run metadata.
page, pageSizePagination controls.
sortSort key.
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

GET /runs/{id}
Returns the run summary — workflow, status, start and end timestamps, model, evaluator output, and cost. 
curl https://your-org.armature.app/api/armature/v1/runs/{id} \
  -H "Authorization: Bearer amt_<key-id>_<secret>"

​
Get the run trace

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

GET /runs/{id}/evaluation
Returns the evaluation evidence: per-criterion results, the judge model’s verdict, and the supporting excerpts.

​
List run tool calls

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. 
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, poll the run until it reaches a terminal state, then fetch the evaluation: 
# 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"