# Record an agent run, or update the one at this address

`POST /api/v1/agent-runs`

MCP tool: `upsert-agent-run`

Keyed by `url`: the first call creates the run, later calls update it. Record it when the run starts (`works_on`, `parent`, `authority`) and again when it ends (`status`, `usage`; without `usage` it counts as `unpriced`). Omitted fields are kept; `usage` merges per key; `works_on` and `produced` only add.
**`works_on` takes the tasks for the run.** One a `running` run outside this run's family (the runs sharing its root through `parent`) already holds is not added: it comes back under `contended` with that run, `null` when it is in a project you cannot reach. Moving off `running` releases what the run took.
An id you cannot reach is returned under `unresolved`, not refused. Write only your own run or one it started; runs under one `agent` are one agent's. `list-agent-runs?lingering=true` finds runs left `running` after their work closed.

## Responses

- `200` — The run's acknowledgement
- `400` — The request does not match the operation's schema
- `404` — No project or task by that id that you can reach