> 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 logs

> View, search, filter, export, and debug execution logs

Use the **Logs** page to inspect, search, filter, and export Flow and Agent executions, including executions that external agents report to Runtype. To send executions from an agent that runs outside Runtype, see [Reporting telemetry from an external agent](/developer-guides/guides/reporting-external-telemetry).

## View execution details

Select a row in the **Logs** list to open the details panel. The header shows the run's source, status, duration, tokens, and cost. The details panel contains the following views and areas:

* **Conversation**: Shows the messages sent and received, when the row belongs to a conversation. This is the default view for those rows.
* **Timeline**: Shows each step in execution order with its status and duration. For a conversation, Timeline shows every run on one time scale. For a flow or execution with no conversation, Timeline is the only view.
* **Together**: Shows Conversation and Timeline side by side, with the inspector on the right.
* **Inspector**: Appears in a column on the right of Timeline and Together. Select a step to see its full input, output, and configuration. With no step selected, the inspector shows the payload of the row that you opened.
* **Token usage**: Shows input and output tokens for prompt steps.
* **Context window**: Shows estimated input tokens for agent turns. It splits them into the system prompt, tool definitions, record context, conversation history, tool results, and current message. It classifies the total by absolute token count as **Typical range**, **Elevated**, or **Very high**. These estimates can differ from billed tokens. When context estimates are available, Timeline's **Context per iteration** chart shows one stacked column per iteration. It uses the same categories and colors as the **Context window** bar. When all iterations share an **Elevated** threshold, a dashed line marks that threshold.
* **Context map**: Appears on a model request in the inspector when the run recorded its context. It shows every block sent to the provider, in the order the provider received them, scaled to the input tokens the provider reported. It also shows how many tokens were read from the cache and, when the model's context window size is known, the share of the window that the request used and the tokens left. When one block is a quarter or more of the request, the map names that block. Use the arrows to step through the other requests in the same turn. The map and the full-screen context view number requests the same way: **Request 6 of 9** in a run with one turn, or **Request 2 of 3 in turn · #6 in run** when the run has more than one turn.

### Explore a run's context

Select **Open context** on a context map, or select a block in its strip, to open the full-screen context view for the run. The view contains the following areas:

* A chart with one column per provider request, so you can see where the context grew and where blocks were removed.
* The selected request's blocks, in the order they were sent.
* The selected block's category, role, token count, character count, and the request that first sent it.
* The selected block's text, when the run stored it. Text is stored only when the agent's **Verbose logging** setting is **On**, and secrets are removed before it is stored. A change to the setting applies to new runs. When a run stored no text, the view says so once, above the chart. When a run stored text but not for one block, that block's request went over the per-request size cap or the run's capture budget ran out. A block longer than 48,000 characters shows its start and end, with a note that says how many of its characters were stored and that the middle was not.

The context view takes keyboard focus when it opens, and its shortcuts work only while focus is inside it. Press `j` or `k` to move to the next or previous block. Press `]` or `[` to move to the next or previous request. Press `Esc` to clear the block selection, and `?` to list the shortcuts. When you move to another request, the selected block stays selected if that request sent it too. Otherwise the view says the block is not in that request, and selects it again when you return to a request that has it. **First sent in request N** opens that request with the block selected. The URL records the request and block, so you can share a link to one block: select **Copy link** in the header to copy it.

A run records context only when the agent's **Verbose logging** setting is **On**. Older runs can have no context map.

When the row names an agent or flow, click **Open agent** or **Open flow** in the header to open that definition. Click **Open full page** to leave the details panel and open the full execution timeline.

### Agent executions

Agent logs show recorded iterations, tool calls, tool results, and reasoning output. Use the trace to inspect tool selection and the final response.

Tool-call details retain parameter names and values that are not protected. The logs do not retain values injected for protected parameters. They replace those values with `[REDACTED]` and identify the parameters as secure.

When verbose logging is off for a run, its details show **Verbose logging off.**, and the run has no stored token counts, cost, or full outputs. To change the setting for an agent, open the agent, select **Logging**, and set **Verbose logging** to **On**, **Off**, or **Inherit from surface**. The **Logging** page also has **Open logs for this agent**, which opens **Logs** filtered to that agent.

### Explain a run with AI

Open the full execution timeline (**Open full page** from a Logs row) and click
**Explain this run** to ask the Runtype Run Investigator system flow to interpret
retained trace evidence. Opening the page alone does not call a model. Analysis uses your account's model access,
execution limits, and normal model usage charges.

The explanation separates **Observed** facts, uncertain **Possible explanations**,
and **Suggested next steps**. Click an **Inspect** citation to reveal its step in
the timeline and open it in the **Step inspector**. These are AI-generated interpretations: verify them
against the evidence. **Quality: not assessed** means this is not a verdict on
whether the task met your business requirements.

**Evidence and limits** discloses the available coverage. The system analyzes
a bounded, redacted excerpt, prioritizing errors and recent events. Truncated
traces, omitted logging-off payloads, and missing totals limit what it can
conclude. Individual span durations and costs can overlap.

Use **Cancel explanation** to stop waiting or retry after an error. An explanation
does not modify the original run, execute its suggestions, or automatically create
an eval case. For an agent trace, **Add to eval** opens the existing capture dialog.

### Capture an agent execution as an eval case

To capture an execution, follow these steps:

1. Open an agent execution.
2. Click **Add to eval**.
3. Select the target eval. If no eval targets the agent, select the **Create default eval for** option, which shows the agent's name. Runtype creates the eval when you save.
4. Select the **Fork point** that the eval grades as the next step.
5. Click **Add to eval**.

The case freezes the conversation before the selected action and grades the agent's next step. If the run has no tool calls, the eval grades the agent's reply. The dialog reports **Fully replayable** when it captures all recorded tool outputs. It reports **Partially replayable** when it truncates a tool output, and the case still grades the next step. For more information, see [Managing eval suites](/user-guide/evals/managing-eval-suites).

## Read a run's origin

Every run records an origin, which names what started the run. Runtype sets the origin from the credential that started the run, and you can't set it in a request. The **Logs** list doesn't show origin. In the run lists for an agent, a flow, or a product's activity, a run started from the dashboard shows a **Dashboard** badge.

The API returns one of the following origin values:

* `dashboard`: A signed-in dashboard session started the run.
* `api`: A management API key started the run. This includes the Runtype MCP server's tools and Code Mode.
* `internal`: A Runtype service started the run.

Some runs have no origin. These include scheduled runs, webhook deliveries, messaging turns, A2A calls, agents exposed as an MCP surface, subagent runs, flows that another flow calls, runs on a client-token product surface, and executions reported through OpenTelemetry. An empty origin on those runs doesn't mean that the caller is unknown. Older runs can also have no origin, even if a person started them from the dashboard. Neither **Logs** nor the runs API can filter by origin. To see what started a run, including a schedule, surface, API key, or MCP client, read the `via` field on the [runs API](/user-guide/logs/runs#list-runs-from-the-api) rows.

## Search and filter logs

Use search and filters to find executions in your log history. By default, **Logs** shows the last hour and hides **Schedule** and **Audit** entries.

Your filters, search, and time range are part of the page URL, so you can bookmark or share a filtered view. Links from an agent, a run, or an execution open **Logs** already filtered to it. To remove that filter, click the **X** on its chip. To reset the other filters, click **Clear filters**.

### Filter logs

Use the following filters:

* **Type**: Shows entries for **Flow**, **Step**, **Agent**, **Tool**, **Batch**, **System**, **Model**, **Schedule**, or **Audit**. The filter covers the whole time range. **Step** lists only Flow steps, and **Flow** lists Flow runs without their steps. **Audit** requires an Enterprise plan. For more information, see [Audit trail](/user-guide/logs/audit-trail).
* **Status**: Shows entries with **Completed**, **Failed**, **Running**, **Queued**, **Cancelled**, or **Unknown** status.
* **Level**: Shows entries at the **INFO**, **WARN**, and **ERROR** levels. Click a level to show or hide it.
* **Time range**: Limits results to the **Last 15 minutes**, **Last hour**, **Last 6 hours**, **Last 24 hours**, **Last 7 days**, **Last 30 days**, or a **Custom range**.

The activity chart over the list shows entry counts across the selected time range. Red bars mark periods that contain errors. To narrow the list to one period, click its bar. The time range changes to **Custom range**.

**Unknown** includes runs that stopped before they reported a final result. These entries show a warning, and their token usage can be missing or partial. Some older entries also show as **Unknown**.

### Search logs

Type keywords in the search field. The search covers the whole time range, not only the entries already loaded. It matches an entry's message, name, operation, tool name, and error class, and it ignores case. For the most recent entries, search matches only the message text.

To narrow by one field, start the query with `status:`, `level:`, or `type:`, for example `status:failed`, `level:error`, or `type:step`. A field query replaces the matching filter selection. A `type:` query always filters by type. If the value names no type, **Logs** shows an error that lists the valid types. If a `status:` or `level:` value matches no status or level, **Logs** searches for the whole query as text.

The prefixes `tool:`, `step:`, `stepName:`, `flow:`, `record:`, `error:`, and `model:` search for their value as plain text, for example `tool:web_search`. **Logs** searches for any other text that contains a colon exactly as you typed it.

The status filter and the status totals classify entries the same way. An entry whose activity never finished is **Unknown**. A finished entry at the error level is **Failed**. Every other finished entry is **Completed**. **Running**, **Queued**, and **Cancelled** don't match any entries in **Logs**.

## Use live mode

Click **Live** in the **Logs** view to show new executions as they start and complete. Use live mode to test a Flow or monitor a scheduled batch run.

Live mode pauses automatically when you review older entries. It resumes when you return to the end of the list.

In live mode, only search, the **Level** filter, and filter chips apply. The **Level** filter adds **DEBUG**. The **Time range**, **Status**, and **Type** filters and **Export** are unavailable until you turn live mode off. To empty the live list, click **Clear stream**.

When live mode is on, the **Logs** view shows a context strip with up to three pills for executions with the newest activity. Each pill includes a mini context bar and its band label. Click a pill to open that execution's details.

## Use keyboard shortcuts

To see all keyboard shortcuts, press `?` in **Logs**. Press `j` and `k` to move between entries, `/` to focus search, `r` to refresh, and `l` to turn live mode on or off. In the Timeline, press `e` to move to the next failed step.

## Export logs

Click **Export**, then select **Export as CSV** or **Export as JSON**. The export includes only the entries loaded in the list. To include older matching entries, scroll to load them before you export.

JSON exports include each entry's available fields. CSV exports include timestamps, levels, types, statuses, titles, subtitles, Flow names, step names, record names, durations, token totals, estimated costs, and errors.

To copy the loaded entries to the clipboard as JSON, click **Copy**.

## Query logs outside the dashboard

You can read the same logs through the following interfaces:

* **API**: `GET /v1/logs` lists entries, and `GET /v1/logs/stats` returns aggregate counts. For request parameters, see the [API reference](/api-reference).
* **CLI**: `runtype logs list` and `runtype logs stats` query stored logs. Both default to the last 24 hours and accept `--from`, `--to`, `--level`, `--type`, `--status`, `--search`, `--flow`, `--agent`, `--execution`, `--conversation`, and `--json`. `runtype tail` streams live logs.
* **MCP server**: The Runtype MCP server provides the `list_logs` and `get_log_stats` tools.

For a workflow that uses these interfaces to find and fix failing agent runs, see [Improving your agents from production traces](/developer-guides/guides/improving-agents-from-production).

## Understand list notices

The **Logs** list shows a notice when it can't read all data for the selected time range. The following table lists each notice and what to do:

| Notice                                                                              | Meaning                                                           | What to do                                                 |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- |
| **Part of this window could not be read. Some entries are missing.**                | The list is incomplete for this time range.                       | Refresh the page, or try again later.                      |
| **Entries from the last few minutes could not be loaded.**                          | The newest entries are missing from the list.                     | Refresh the page, or turn on live mode to see new entries. |
| **Counts could not be read. The totals shown cover only the entries on this page.** | The status, type, and level totals count only the loaded entries. | Refresh the page to read the full totals.                  |
| **Counts start on** a date, followed by **earlier logs are not in the store.**      | No counts exist before that date.                                 | Select a time range that starts after that date.           |

## Debug failed executions

When a Flow or Agent execution fails, the **Logs** page shows the failed step and its error details.

### Identify the failed step

Open a failed execution. In the **Timeline**, find the step with an error status, or press `e` to move to the next failed step. Select that step to review its error message and input in the inspector.

### Review common failure patterns

The following table lists common failure patterns and fixes:

| Pattern              | Cause                                                                       | Fix                                                                                                                                                                                      |
| -------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Model errors**     | Rate limits or invalid API key                                              | Select the model call in the **Timeline**. The inspector shows the provider's **HTTP status**, **Error class**, and **Rate limits**. Then check the model configuration in **Settings**. |
| **Transform errors** | JavaScript error in a `transform-data` step                                 | Review the script and the input data that it received.                                                                                                                                   |
| **Fetch errors**     | External API timeout, authentication failure, or unexpected response format | Verify the URL, credentials, and expected response shape.                                                                                                                                |
| **Record errors**    | An `upsert-record` step received non-JSON data                              | Set `sourceVariable` to a value that resolves to a JSON object, not a plain string.                                                                                                      |

### Re-run after a fix

After you fix the issue, run the Flow manually from **Flows**. If the Flow uses a **Schedule**, wait for its next scheduled execution.

## Next steps

Use the following pages to continue:

* [Debugging flows](/user-guide/flows/debugging-flows): troubleshoot Flow execution errors
* [Flow execution failures](/user-guide/troubleshooting-faq/flow-execution-failures): review common failure patterns
* [What are logs?](/user-guide/logs/what-are-logs): learn what Logs captures
* [Audit trail](/user-guide/logs/audit-trail): review account activity in Logs
* [Improving your agents from production traces](/developer-guides/guides/improving-agents-from-production): query logs through the API, CLI, or MCP server
* [Working with runs](/user-guide/logs/working-with-runs): find runs and read the run detail page
* [Querying logs programmatically](/user-guide/logs/querying-logs-programmatically): query logs with the API, `runtype logs`, and `runtype tail`
* [Logging policy and PII redaction](/user-guide/logs/logging-policy-and-redaction): control verbose logging and PII redaction, and see which setting wins
* [Agent execution failures](/user-guide/troubleshooting-faq/agent-execution-failures): diagnose failed Agent runs, stop reasons, and tool errors