# Runs

> List runs, the requests that share a trace id, with duration, errors, models, estimated provider cost, scores and prompt versions, filtered and sorted.

Source: https://infro.io/docs/observability/runs

A run is the requests of one workflow that carried the same `trace_id`: an agent turn, a retrieval-augmented answer, a document pipeline. Send `metadata.trace_id` (or `X-INFRO-Trace-Id`) and `metadata.workflow` on each call, as [Request traces](https://infro.io/docs/observability/traces#group-requests-into-a-run) describes, and `GET /v1/runs` lists one row per run, so you can find the expensive, slow or failing ones without reading every request. Runs are grouped by workflow and trace id together, because trace ids are yours and two workflows can reuse one. A request with no `trace_id` belongs to no run.

## List runs

```bash
curl "https://api.infro.io/v1/runs?workflow=support-answer&sort=costliest&has_errors=true" \
  -H "Authorization: Bearer $INFRO_API_KEY"
```

The key needs history access, as `GET /v1/requests` does: a `scoped` key sees the runs of its own project (or its own requests), an `organization` key every run. Each figure covers only the requests the key may read.

- `from, to` (ISO 8601) — The window. Default: the 24 hours before `to`, and `to` defaults to now. At most 31 days apart, and never earlier than your plan's request history; `window_start` says where the search began.
- `sort` (string) — `newest` (default, by start time), `costliest` (estimated provider cost), `slowest` (duration) or `errors` (failed requests). Highest first.
- `min_cost` (string) — Only runs whose estimated provider cost is at least this many US dollars, for example `0.25`.
- `has_errors` (boolean) — `true`: runs with at least one request that ended with a status of 400 or above. `false`: runs with none.
- `score_below` (number) — Only runs whose mean numeric [score](https://infro.io/docs/observability/scores) is below this value. Runs with no numeric score are left out.
- `limit` (integer) — Runs per page, 1 to 100. Default 25.
- `after` (string) — The previous page's `next_cursor`, unchanged. Keep the same filters and `sort`; a page never skips or repeats a run while new requests arrive.
- `every request filter` (query) — `model`, `project`, `key`, `provider`, `connection`, `route`, `endpoint`, `modality`, `surface`, `status`, `trace_id`, `workflow`, `step`, `feature`, `user_id`, `session_id`, `tag.<name>` and the rest of [the request log's filters](https://infro.io/docs/observability/traces#list-and-retrieve-requests) choose which requests are grouped, before grouping. `model=openai/gpt-5` lists the runs that called that model, with their figures over the requests that match.

## Response

```json
{
  "object": "list",
  "data": [
    {
      "object": "run",
      "trace_id": "run_42",
      "workflow": "support-answer",
      "started_at": "2026-11-16T09:14:02.120Z",
      "ended_at": "2026-11-16T09:14:09.884Z",
      "duration_ms": 7764,
      "requests": 4,
      "errors": 1,
      "cost": 0.01832,
      "cost_is_partial": false,
      "unpriced_requests": 0,
      "models": ["anthropic/claude-sonnet-5", "openai/text-embedding-3-small"],
      "user_id": "cus_8812",
      "session_id": null,
      "score": { "count": 2, "mean": 0.8, "thumbs_up": 1, "thumbs_down": 0 },
      "prompt_versions": [{ "id": "prm_01JD…", "slug": "support-reply", "version": 3 }]
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ2Ijoi…",
  "window_start": "2026-11-15T09:20:00.000Z",
  "window_end": "2026-11-16T09:20:00.000Z",
  "retention_days": 30,
  "sort": "costliest",
  "covers": "model_calls_through_infro"
}
```

- `duration_ms` (integer) — From the first request's start to the end of the last one to finish.
- `requests, errors` (integer) — Requests in the run, and how many ended with a status of 400 or above.
- `cost` (number) — The sum of INFRO's estimates of what your providers bill for the run's model calls, in USD. INFRO adds nothing to it. When a successful request in the run was unpriced, `cost` is a lower bound and `cost_is_partial` is `true`, with the count in `unpriced_requests`; nothing is filled in.
- `models` (array) — Every model the run's requests named, sorted.
- `user_id, session_id` (string | null) — Set when every request of the run that carries one carries the same value; `null` otherwise.
- `score` (object) — The run's [scores](https://infro.io/docs/observability/scores): `count`, `mean` of the numeric ones (`null` when there are none), and `thumbs_up` / `thumbs_down` for true/false scores.
- `prompt_versions` (array) — Each [managed prompt](https://infro.io/docs/features/prompts) version the run's requests were served from: `id`, `slug` (`null` if the prompt can no longer be found) and `version`.
- `covers` (string) — Always `model_calls_through_infro`: your vector database, retrieval and own compute are not in any figure.

For one run's requests in order, with cost by step, call `GET /v1/traces/{trace_id}`. The console lists the same runs, and opens a run's steps from a row.

## Through the management API and MCP

`GET /manage/v1/runs` takes the same parameters with a [management token](https://infro.io/docs/manage/tokens) holding `analytics:read`, and never returns request content. The [INFRO MCP server](https://infro.io/docs/mcp)'s `list_runs` tool reads the same list for an assistant, and `search_requests` takes `workflow` and `step` filters.
