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

# What are Logs?

Logs record every Flow and Agent execution so you can see what ran and why it failed. A log entry shows when an execution started, which steps ran, what data moved between them, and whether the execution succeeded. Agents that run outside Runtype can also send their executions to Logs. See [Reporting telemetry from an external agent](/developer-guides/guides/reporting-external-telemetry).

When your plan includes the audit trail, Logs also records workspace changes. The [Audit trail](/user-guide/logs/audit-trail) shows who changed each Flow, Agent, and Record.

## How logs work

Open **Logs** from the sidebar to see recent entries. Each row is one part of an execution, such as a Flow run, an Agent run, a step, or a tool call. A step's start and finish appear as one row with a duration, not as two rows. Smaller events inside a run, such as skipped steps, artifacts, and custom events, don't get their own rows. To see them, open the row and select **Timeline**.

An execution that is still running might not appear in the list until it finishes.

Audit and schedule entries aren't part of an execution. The default **Type** filter hides them. To include them in the list, select **Audit** or **Schedule** in the **Type** filter. They appear in time order with the other entries.

### What an entry contains

Depending on the event, a log entry can include the following details:

* **Status**: Shows whether the execution completed, failed, is still running, or has an unknown outcome. If an execution stopped before it could report a result, its status is unknown and any usage shown might be partial.
* **Duration**: Shows how long the operation took.
* **Step details**: Show the input and output for each step, including prompt responses, transform results, and tool calls.
* **Error information**: Shows the error message and identifies the failed step.
* **Metadata**: Shows the processed Record, the model used, and token counts for prompt steps.

Logs redact fields that hold secrets, such as API keys and tokens, before they store an entry. If a Surface sets **PII redaction** to **Redact**, Logs also redact personal data from that Surface's executions.

### Verbose logging

Verbose logging controls whether executions store token counts, cost, and full outputs. It is on by default. When it's off, those details aren't stored, and the detail view shows **Verbose logging off**.

You can set verbose logging in these places:

* **Agent**: On the Agent's **Logging** settings page, set **Verbose logging** to **Inherit from surface**, **On**, or **Off**. **Inherit from surface** uses the Surface or Product setting.
* **Surface**: On the Surface's **Access & keys** page, under **Data**, set **Logging policy** to **Default**, **On**, or **Off**.

The most specific setting wins. An Agent or Flow setting overrides the Surface setting, and a Surface setting overrides the Product setting.

### Other ways to read logs

You can read the same entries outside the dashboard:

* **CLI**: `runtype logs list` queries entries, `runtype logs stats` shows totals, and `runtype tail` streams new entries as they arrive.
* **MCP**: The [Runtype MCP server](/developer-guides/integrations/runtype-mcp-server) provides the `list_logs`, `get_log_stats`, `trace_execution`, and `trace_conversation` tools.
* **API**: `GET /v1/logs` lists entries, and `GET /v1/logs/stats` returns totals. For request parameters, see the [API reference](/api-reference).

## Example

Alex's Flow failed on one Record. Alex opens **Logs**, sets the **Status** filter to **Failed**, and selects the failed row. The error information identifies the step that failed. Alex compares that step's input and output, and finds that the previous step returned an empty field.

Over time, Alex also reviews Logs to find steps that are often slow and inputs that often fail.

## Log retention

Logs are kept for a period that depends on your plan. The banner at the top of the **Logs** page shows your retention period. Plans with unlimited retention don't show the banner.

Entries older than the retention period are no longer available. To keep entries longer, [export them](/user-guide/logs/working-with-logs#export-logs) first or upgrade your plan.

If Logs can't load, the **Logs** page shows an error with a **Retry** option instead of a partial list. New entries are still recorded, and they appear once Logs can load again.

## Next steps

* [Working with Logs](/user-guide/logs/working-with-logs): view execution details, filter, search, and export
* [Audit trail](/user-guide/logs/audit-trail): review who changed each Flow, Agent, and Record
* [Debugging flows](/user-guide/flows/debugging-flows): troubleshoot Flow execution issues
* [Reporting telemetry from an external agent](/developer-guides/guides/reporting-external-telemetry): send runs from agents outside Runtype to Logs
* [What are Flows?](/user-guide/flows/what-are-flows): learn how Flows produce log entries
* [Braintrust (tracing)](/user-guide/integrations/braintrust-tracing): send execution traces to Braintrust
* [Working with runs](/user-guide/logs/working-with-runs): find runs and read the run detail page
* [Logging policy and PII redaction](/user-guide/logs/logging-policy-and-redaction): control verbose logging and PII redaction, and see which setting wins