Read run diagnostics, follow new runs, and summarize failures and latency.
sim logs is also spelled sim log.
These commands accept the global options.
List run logs, such as failed or errored runs, by workflow, trigger or time
sim logs list [options]Options
| Option | Required | Description |
|---|---|---|
--workflow <value...> | 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 <value...> | 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 <value> | No | Severity level to include. Accepted values: info, error. |
--start-date <value> | 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 <value> | 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 <value> | 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 <value> | 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 <value> | 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 <value> | 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 <value> | No | AI model used during execution. |
--details <value> | 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 <n> | No | Maximum items to return (0 for everything). Defaults to 100. |
--cursor <value> | 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 <value> | 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 <value> | 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 <value> | No | Exact run identifier to match. |
--sort-by <value> | 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 <value> | No | Sort direction. Defaults to "desc". Accepted values: asc, desc. |
--folder <value...> | 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.
Show run diagnostics
sim logs get <runId> [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.
Summarize run counts, failures and latency over a window
sim logs stats [options]Options
| Option | Required | Description |
|---|---|---|
--workflow <value...> | 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 <value...> | 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 <value...> | 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 <value> | 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 <value> | 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 <value> | 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 <value> | 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 <value> | 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.
Watch runs live as they arrive, printing each new run once
sim logs follow [options]Options
| Option | Required | Description |
|---|---|---|
--workflow <id> | No | Only follow runs of this workflow (repeatable). |
--folder <path> | No | Only follow runs of workflows in this folder (repeatable). |
--trigger <type> | No | Only follow runs with this trigger type (repeatable). |
--level <level> | No | Only follow runs at this severity. Accepted values: info, error. |
--details <level> | No | Response detail level; full names each run’s workflow. Accepted values: basic, full. Defaults to full. |
-n, --lines <count> | No | Recent runs to print before watching. Defaults to 10. |
--interval <seconds> | 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
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.