# Runs

> A run is one execution of an agent: its steps, calls, cost and outcome.

A **run** is one execution of a pack’s agents: the steps each agent took, the models it called, the tools and searches it used, what it cost, how long it took and how it ended. LightHouse sees a run as counts and timings, never as content.

## What a run records

| Record       | What it holds                                                                                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run`        | Pack, card, status, duration, attempt, what started it (`schedule`, `agent`, `person` or `api`), and whether it is still running                                            |
| `step`       | Each step: its kind (`agent`, `model`, `tool`, `retrieval`, `approval`, `grounding`, `screening`, `delivery`), duration, status, model, and the counts and sizes in and out |
| `model_call` | Model, backend, input, cached and output tokens, cost, latency, outcome                                                                                                     |
| `retrieval`  | Candidates considered, passages returned, tokens sent and avoided                                                                                                           |
| `outcome`    | What the output was used for, human time saved where known, and whether a person edited it                                                                                  |

A run’s status is one of `ok`, `failed`, `awaiting-approval`, `approved`, `rejected`, `skipped`, `running` or `stalled`.

## Active and stalled runs

A run is reported as it starts and as each step starts and finishes, so LightHouse shows it live. A running run with no word from its deployment for five minutes is shown as **stalled**.

## Run IDs

LightHouse never sees your deployment’s own run ID. It sees `run_id_hash`, a keyed hash of it, and every API route and MCP tool uses that.

## The run map

The run map draws one run: every step in order, which model each step used, the tools and searches, the evidence, the cost and any sign-off. See [The run map](/build/run-map/).

## In LightHouse and the API

- **Agents → Activity** shows runs live; **Insights → Runs** lists them; each run opens its run map.
- `GET /api/v1/runs` (filter by `pack`, `card`, `status`, `since`; paged), `GET /api/v1/runs/{run_id_hash}`, `GET /api/v1/runs/{run_id_hash}/map`, `GET /api/v1/runs/active` and a live stream at `GET /api/v1/runs/active/stream`. See the [Read reference](/api/reference/read/#runs).
- MCP: [`runs`](/mcp/tools/runs/), [`run`](/mcp/tools/run/), [`run_map`](/mcp/tools/run-map/), [`active_runs`](/mcp/tools/active-runs/).

Source: https://docs.atlanticagenticlabs.com/concepts/runs/