# Logs (/cli/logs) Read run diagnostics, follow new runs, and summarize failures and latency. `sim logs` is also spelled `sim log`. These commands accept the [global options](/cli/commands#global-options). ## List run logs, such as failed or errored runs, by workflow, trigger or time \[#list-run-logs-such-as-failed-or-errored-runs-by-workflow-trigger-or-time] ```bash sim logs list [options] ``` **Options** | Option | Required | Description | | - | - | - | | `--workflow ` | No | Comma-separated workflow identifiers to include. An empty entry is rejected. At most 200 entries. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). | | `--trigger ` | No | Comma-separated, lowercase trigger types or webhook provider IDs. Matching is exact and case-sensitive; unknown values select no runs. An empty entry is rejected. The sentinel `all` disables this filter, even when listed with other values. At most 100 entries. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). | | `--level ` | No | Severity level to include. Accepted values: `info`, `error`. | | `--start-date ` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. | | `--end-date ` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. | | `--min-duration-ms ` | No | Minimum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected. | | `--max-duration-ms ` | No | Maximum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected. | | `--min-cost ` | No | Minimum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run. | | `--max-cost ` | No | Maximum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run. | | `--model ` | No | AI model used during execution. | | `--details ` | No | Response detail level; full is requested by default to name each run’s workflow. Accepted values: `basic`, `full`. | | `--include-trace-spans` | No | Include trace spans in JSON or YAML output (implies full detail). | | `--include-final-output` | No | Include final output in JSON or YAML output (implies full detail). | | `--limit ` | No | Maximum items to return (0 for everything). Defaults to `100`. | | `--cursor ` | No | Continue from nextCursor returned by a previous result. | | `--include-handled-errors` | No | Whether `level=error` also selects runs that finished at `info` after a block error was recovered by an error path. Off by default: such a run succeeded, so it is an error only to a caller auditing error handling. Every row reports `hasHandledErrors` whether or not this is set. Job runs carry no block trace, so the flag never widens that branch. | | `--no-include-handled-errors` | No | Send --include-handled-errors as false. | | `--status ` | No | Comma-separated execution statuses to include, from `pending` \| `running` \| `paused` \| `redacting` \| `completed` \| `failed` \| `cancelled`. An empty entry is rejected. ANDed with `level`, which reports severity rather than lifecycle. | | `--workflow-name ` | No | Case-insensitive substring match against the run's workflow name. Runs whose workflow has been deleted match nothing, because the name is no longer joinable. | | `--include-job-runs` | No | Include Chat and Sim-agent jobs alongside workflow runs. Jobs use `kind: "job"` and have no workflow or cost ledger. Workflow, folder, model, or status filters exclude jobs. This option is valid only when sorting by `startedAt`. | | `--no-include-job-runs` | No | Send --include-job-runs as false. | | `--run-id ` | No | Exact run identifier to match. | | `--sort-by ` | No | Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs sort before recorded values in ascending order and after them in descending order. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included. Defaults to "startedAt". Accepted values: `startedAt`, `durationMs`, `cost`, `status`. | | `--sort-order ` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. | | `--folder ` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). | API request and response schemas: [listLogs](/api-reference/logs/listLogs). ## Show run diagnostics \[#show-run-diagnostics] ```bash sim logs get [options] ``` **Arguments** | Argument | Required | Description | | - | - | - | | `runId` | Yes | Unique workflow run identifier. | **Options** | Option | Required | Description | | - | - | - | | `--include-workflow-state` | No | Include the saved workflow snapshot (default: true; Sim’s in-app agent leaves it out unless this flag is passed). Set false to omit block configuration from a log read. Other run fields are unchanged. | | `--no-include-workflow-state` | No | Send --include-workflow-state as false. | | `--trace` | No | Show expanded trace spans with inputs, outputs, errors, timing, and cost. | API request and response schemas: [getLog](/api-reference/logs/getLog). ## Summarize run counts, failures and latency over a window \[#summarize-run-counts-failures-and-latency-over-a-window] ```bash sim logs stats [options] ``` **Options** | Option | Required | Description | | - | - | - | | `--workflow ` | No | Comma-separated workflow identifiers to include. At most 200 entries. An empty entry is rejected. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). | | `--folder ` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). | | `--trigger ` | No | Comma-separated trigger types to include. An empty entry is rejected. The vocabulary is open, so an unrecognized member selects no runs; the literal `all` disables this filter. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). | | `--level ` | No | Severity level to include. Accepted values: `info`, `error`. | | `--include-handled-errors` | No | Whether runs with a handled block error are counted as `handledErrorRuns`, and whether `level=error` also selects them. Off by default: counting them scans each run’s stored trace. | | `--no-include-handled-errors` | No | Send --include-handled-errors as false. | | `--start-date ` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. | | `--end-date ` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. | | `--segment-count ` | No | Number of equal time buckets to divide the window into, from 1 to 500. It is the ceiling on how many buckets a series carries: with `includeEmpty=true` exactly this many are returned, otherwise only the buckets holding at least one run. Buckets are never narrower than one minute, so on a short window the series extends past the end of the window rather than being compressed, and the trailing buckets are empty. Defaults to 72. | | `--include-empty ` | No | Whether buckets with no runs are included in every series. Off by default, so each series carries only the buckets that hold at least one run; set it to publish exactly `segmentCount` buckets per series, empty ones included. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected. Accepted values: `true`, `1`, `yes`, `on`, `y`, `enabled`, `false`, `0`, `no`, `off`, `n`, `disabled`. | API request and response schemas: [getLogStats](/api-reference/logs/getLogStats). ## Watch runs live as they arrive, printing each new run once \[#watch-runs-live-as-they-arrive-printing-each-new-run-once] ```bash sim logs follow [options] ``` **Options** | Option | Required | Description | | - | - | - | | `--workflow ` | No | Only follow runs of this workflow (repeatable). | | `--folder ` | No | Only follow runs of workflows in this folder (repeatable). | | `--trigger ` | No | Only follow runs with this trigger type (repeatable). | | `--level ` | No | Only follow runs at this severity. Accepted values: `info`, `error`. | | `--details ` | No | Response detail level; full names each run’s workflow. Accepted values: `basic`, `full`. Defaults to `full`. | | `-n, --lines ` | No | Recent runs to print before watching. Defaults to `10`. | | `--interval ` | No | Seconds between polls. Defaults to `3`. | Each run prints once, when it is first seen, so its status is the status it had at that moment. With --output json every run is a JSON object on its own line (JSONL) rather than a member of an array, because a follow never ends and so can never close one; --output yaml emits a --- separated document stream. Progress and retries go to stderr, leaving stdout a clean stream of rows. Ctrl-C stops the follow. **Examples** ```bash sim logs follow --level error sim logs follow --workflow 00000000-0000-4000-8000-000000000000 -n 0 sim --output json logs follow | jq -r '.runId' ``` API request and response schemas: [listLogs](/api-reference/logs/listLogs). ## Related docs \[#related-docs] - [Logs and debugging](/logs-debugging) - [Output formats](/cli/output)