Working with 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.

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.

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

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:

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:

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: troubleshoot Flow execution errors
• Flow execution failures: review common failure patterns
• What are logs?: learn what Logs captures
• Audit trail: review account activity in Logs
• Improving your agents from production traces: query logs through the API, CLI, or MCP server
• Working with runs: find runs and read the run detail page
• Querying logs programmatically: query logs with the API, runtype logs, and runtype tail
• Logging policy and PII redaction: control verbose logging and PII redaction, and see which setting wins
• Agent execution failures: diagnose failed Agent runs, stop reasons, and tool errors