# List runs and what they cost

`GET /api/v1/agent-runs`

MCP tool: `list-agent-runs`

The newest matching runs, `totals` over every match, and with `group_by` the totals per value. Filters intersect. `peak_context` is the largest, every other counter a sum; `unpriced` counts runs with no `cost_usd` yet. A run on several tasks counts in each `task` or `tag` group. `task` with `status=running` lists the runs holding a task.

## Parameters

- `project` (query, optional)
- `task` (query, optional) — Runs that worked on this task.
- `upstream_of` (query, optional) — Runs that worked on this task or anything that `blocks` it, closed work included: the cost of a milestone.
- `tag` (query, optional) — Runs that worked on a task with this tag.
- `model` (query, optional)
- `agent` (query, optional)
- `parent` (query, optional) — The children of this run.
- `by` (query, optional) — Runs whose recording credential is: `me` (you alone, not your teams), a `user_…`, or a `team_…` (any member). Each row's `by` is that `user_…`, `null` on old runs. Your run limit: `agent`, `status=running`, `by=me`.
- `status` (query, optional)
- `linked` (query, optional) — `false`: runs that worked on no task.
- `lingering` (query, optional) — `true`: still `running` though every task it worked on is closed.
- `since` (query, optional) — Started at or after.
- `until` (query, optional) — Started before.
- `group_by` (query, optional) One of: model, agent, status, project, task, tag.
- `limit` (query, optional) — Rows to return, default 20; `0` for totals alone.

## Responses

- `200` — The runs, their totals and groups
- `400` — The request does not match the operation's schema
- `404` — No project or task by that id that you can reach