Skip to navigation
Logs

Working with runs

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.

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.

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.
  • 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.

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.
  • 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
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
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.

Next steps

Use the following pages to continue: