> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Working with runs

> Review an agent's or a flow's past runs, read a run's detail page, and act on its run insights.

A run is one execution of an agent or a flow, from its first input to its final result. The dashboard lists runs on each agent and flow, and in a product's **Activity** view. Use a run list to answer questions about one agent or flow, such as which of its recent runs failed and which version produced them.

## Runs and Logs

Runs and **Logs** read the same executions at different levels of detail:

* A run list has one row per run, scoped to one agent or flow. A run that starts subagents or nested flows shows a count, such as **2 children**, and you can expand the row to list them under their parent.
* **Logs** lists every entry across your account, including each step, tool call, and model call, and it can filter by type, status, level, and time.

Start from a run list when you know which agent or flow to check. Start from **Logs** when you search across everything. For more information, see [Working with logs](/user-guide/logs/working-with-logs).

## Open a run list

Each run list shows runs newest first. Where you open it depends on what ran:

* **Agent**: Open the agent and select the **Runs** tab. The tab shows how many runs the list holds, and a red marker when one of them failed. The list holds the agent's 50 most recent runs and refreshes every few seconds.
* **Flow**: Open the flow, click **Save options** (the arrow beside the save button), and select **Runs**. The **Runs** panel lists the flow's runs with their **Status**, **Started**, **Duration**, and **Cost**. Select a run to open its timeline in **Logs**.
* **Product**: Open the product and click **Activity**. Activity lists the agent runs and conversations from every surface of the product. For more information, see [Product views](/user-guide/products-surfaces/product-views).

The **Runs** tab appears after you save the agent for the first time.

## Filter an agent's runs

The agent's **Runs** tab has the following controls:

* **Search runs...**: Matches the run's title, execution ID, and surface type.
* **All**, **Completed**, and **Failed**: Filter by status. **Failed** also counts cancelled and interrupted runs.
* **Slow**: Shows runs that took 5 seconds or longer.
* **Hide dashboard runs**: Hides the runs that you and your teammates started from the dashboard. The button appears only when the list contains one.
* **Group by version**: Stacks runs under the agent version that ran them. The dashboard remembers this setting in your browser.

Each group header shows the version, the number of runs, and how many failed, for example `v3 · 12 runs · 2 failed`. Runs that tested unsaved changes from the editor group under **Unsaved editor config**. Runs that recorded no version group under **No version reported**.

To move through the list with the keyboard, press `j` and `k`. Press `Enter` to open the focused run, `/` to search, and `Escape` to clear the search and filters.

## Read a run's badges

A row can show the following badges:

* **Dashboard**: A signed-in dashboard session started the run, for example from the editor's test panel. Scheduled, webhook, and messaging runs never show this badge.
* **External**: An agent that runs outside Runtype reported the run. Its timings and cost are what the agent reported. For more information, see [Reporting telemetry from an external agent](/developer-guides/guides/reporting-external-telemetry).
* A version label, such as `v3 · Nightly`, when the list isn't grouped by version.

For the origin values that the API returns and the runs that have no origin, see "Read a run's origin" in [Working with logs](/user-guide/logs/working-with-logs).

## Read the run detail page

Select a run on an agent's **Runs** tab to open its detail page. Selecting an agent run in a product's **Activity** view opens the same detail in a narrower layout.

The header shows the following information:

* The first eight characters of the execution ID. Click the ID to open the run's full timeline in **Logs**. Click the copy icon beside it to copy the full ID.
* When the run started, and the surface type that started it.
* The agent version that ran, and `pinned` or `alias` when the request selected a version by ID or by alias.
* The run's status.

Under the header, the transcript sits on the left and the timeline on the right. Drag the divider to resize them, or double-click it to reset. To give the timeline the full width, click **Expand the timeline**, the icon over the timeline.

The transcript starts with a one-sentence summary of the outcome, such as `Answered after 3 turns.` or `Failed after 2 turns.` When a step failed, the summary names the step and its first error sentence. Under the summary, the page names the agent or flow that produced the run, with a link to edit it.

## Act on run insights

The detail page compares the open run with the agent's 50 most recent runs. When the comparison finds something, a box under the summary lists it. The box can show the following insights:

* **Version failing more often**: The run's version fails at least twice as often as the version before it. Both versions need at least five runs in the window.
* **Failing tool**: A tool failed in at least 20% of its calls, with at least three calls in the window.
* **Tools never called**: Some tools attached to the published version weren't called in any of its recent runs. Click **Open tools** to review them. Every attached tool adds its definition to each model request, so removing unused tools reduces input tokens. For more information, see [Agent tools](/user-guide/agents/agent-tools).
* **Cost outlier**: The run cost more than twice the average of the recent runs.

The box doesn't appear when nothing stands out. A run from an external agent shows fewer insights, because it reports no attached tools or versions.

To read the same comparison from code, call `GET /v1/agents/{id}/run-insights` with an API key that has `AGENTS:READ`. The `limit` query parameter sets how many recent runs to compare, up to 200. The default is 50.

**`Read run insights for an agent`**

```bash title="Read run insights for an agent"
curl "https://api.runtype.com/v1/agents/agent_YOUR_AGENT_ID/run-insights?limit=100" \
  -H "Authorization: Bearer rt_YOUR_API_KEY"
```

Replace the following:

* `agent_YOUR_AGENT_ID`: the ID of the agent.
* `rt_YOUR_API_KEY`: an API key with `AGENTS:READ`.

The response lists run and failure counts per version, call and failure counts per tool, the attached tools that weren't called, and the average tokens and cost per run.

## Re-run a run

On an agent's **Runs** tab, the detail page has two re-run buttons:

* **Re-run**: Runs the agent again with the same input messages. Before it starts, a dialog asks you to confirm. Tool calls run again, so a tool that sends messages or writes data does so a second time. The second run appears at the top of the list. The button is unavailable when the run recorded no input messages.
* **Re-run with current version**: Opens the agent's test panel so you can run the agent as it is saved now. This button doesn't appear for runs from an external agent.

## List runs from the API

`GET /v1/runs` returns the same runs as the dashboard lists, one row per run. Filter by `agentId` or `flowId`, and by `status`, which accepts `running`, `completed`, or `failed`. The window defaults to the last 24 hours. Use `from` and `to` to change it. The Runtype MCP server provides the same list as the `list_runs` tool.

**`List an agent's failed runs`**

```bash title="List an agent's failed runs"
curl "https://api.runtype.com/v1/runs?agentId=agent_YOUR_AGENT_ID&status=failed" \
  -H "Authorization: Bearer rt_YOUR_API_KEY"
```

Each row can carry a `via` object that says how the run started. Its `kind` is one of `schedule`, `surface`, `api`, `mcp`, `cli`, `test`, or `eval`, and its `id` and `label` name the schedule, surface, API key, or client that started the run. `via` is null for runs that started before Runtype recorded it and for entrances that state nothing. In that case, read `origin` instead. Treat `label` as display text only. The names of `mcp` and `cli` clients are self-declared, so don't use them to make an access decision.

To show a total, add `includeCount=true`. The response then includes `pagination.totalCount`, the number of runs that match your filters and window, counted up to 1000. When more than 1000 runs match, `pagination.totalCount` is 1000 and `pagination.totalCountCapped` is `true`. Any other value, or no value, returns no count.

For every parameter and field, see [List runs](/api-reference/runtype-api/runs/list-runs).

## Next steps

Use the following pages to continue:

* [Working with logs](/user-guide/logs/working-with-logs): search every execution and read a run's full timeline
* [Agent versioning and publishing](/user-guide/agents/agent-versioning-and-publishing): compare and roll back the versions that your runs group under
* [Product views](/user-guide/products-surfaces/product-views): review a product's runs and conversations in Activity