> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# deepline runs

> Inspect, watch, stop, and export play runs.

## runs

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs [options] [command]

Inspect, watch, stop, and export play runs.

Options:
  -h, --help                        display help for command

Commands:
  children [options] <parentRunId>  List async child Runs for one launch key,
                                    one page at a time.
  history [options]                 Page workspace run history.
  events [options] [runId]          Query, count or summarize retained run
                                    events.
  rows-history [options] <runId>    Read one immutable run-row history page;
                                    incomplete historical capture is reported
                                    explicitly.
  status [options] <runId>          Legacy scalar-only read. Use runs get for
                                    canonical status, progress, logs, and
                                    results.
  get [options] <runId>             Get a play run, or a tool call deepline run
                                    made, by the id its receipt gave.
  rerun [options] <runId>           Start a fresh run from a prior run's
                                    retained input and pinned revision.
  list [options]                    List play runs.
  stop-all [options]                Stop active play runs in the current
                                    workspace.
  watch|tail [options] <runId>      Poll the canonical run snapshot until
                                    terminal status.
  logs [options] [runId]            Read a run’s logs or search recent events.
  stop [options] <runId>            Stop a play run.
  export [options] <runId>          Export a play run dataset to a CSV or JSON
                                    file.
  help [command]                    display help for command
```

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Explanation:
  Purpose:
    Everything about executions of plays: current status, row outcomes, logs,
    cost, export, and cancellation.
  Which command:
    runs get <run-id>        status, step progress, dataset handles, next steps
    runs export <run-id> --out f.csv   the result rows as CSV
    billing usage --run-id <run-id>    what the run cost
    runs list --play <ref>   recent runs of a play with status and credits
    runs logs <run-id>       persisted logs; --failed for the failure window
    runs watch <run-id>      follow an active run until it ends
    runs stop <run-id>       cancel; runs stop-all cancels every active run
  Ids:
    play/<play-ref>/run/<timestamp>-<suffix>, printed in run's receipt as Id.
  Cost:
    All of these are free; a run's spend was charged while it ran.
```

## runs children

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs children [options] <parentRunId>

List async child Runs for one launch key, one page at a time.

Options:
  --launch-key <key>  Authored deepline.runPlayAsync launch key
  --cursor <cursor>   Opaque cursor from the previous page
  --limit <number>    Rows to request (1–50; default 50) (default: "50")
  --json              Emit JSON output
  -h, --help          display help for command
```

## runs history

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs history [options]

Page workspace run history.

Options:
  --cursor <cursor>  Opaque nextCursor returned by the previous page
  --limit <count>    Maximum runs on this page
  --search <text>    Search Play/workflow names, run IDs and statuses
  --type <type>      Search all, plays or monitors (requires --search)
  --org <id>         Workspace ID (must match the authenticated workspace)
  --json             Emit JSON output
  -h, --help         display help for command
```

## runs events

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs events [options] [runId]

Query, count or summarize retained run events.

Options:
  --since <time>       Inclusive UTC time or lookback such as 1h
  --until <time>       Exclusive UTC time
  --play <name>        Exact Play name
  --kind <kind>        Exact event kind
  --where <filter>     Typed comparisons with &&, || and parentheses
  --step <id>          Exact authored step ID
  --level <level>      Minimum severity: debug, info, warn or error
  --query <text>       Literal text in the full retained log message
  --count              Exact retained count; no limit, cursor or payloads
  --group-by <fields>  Count groups by comma-separated fields
  --sum <field>        Count and sum numeric values; repeatable, optionally
                       grouped (default: [])
  --fields             Discover filter fields, types and operators
  --limit <count>      Rows or groups per page (maximum 200)
  --cursor <token>     Continue the exact preceding query
  --payloads           Include saved details: at most 10 events and 16 MiB
  --json               JSON output
  -h, --help           display help for command
```

## runs rows-history

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs rows-history [options] <runId>

Read one immutable run-row history page; incomplete historical capture is
reported explicitly.

Options:
  --play <name>          Play reference owning this dataset
  --dataset <namespace>  Recorded table namespace from the run dataset metadata
  --limit <rows>         History entries per page (1 to 1000) (default: "200")
  --cursor <cursor>      Opaque nextCursor from the previous page
  --json                 Emit rows and coverage metadata as JSON
  -h, --help             display help for command
```

## runs status

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs status [options] <runId>

Legacy scalar-only read. Use runs get for canonical status, progress, logs, and
results.

Options:
  --json      Emit JSON output
  -h, --help  display help for command
```

## runs get

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs get [options] <runId>

Get a play run, or a tool call deepline run made, by the id its receipt gave.

Options:
  --json [fields]  JSON output; optionally select comma-separated dotted paths
                   (run.status,datasets,actions)
  --full           Include the complete retained result and raw diagnostics
  --input          Explicitly print the original retained input JSON (may
                   contain customer data)
  --config         Explicitly print the recorded configuration, without full
                   results
  --web-url        Print only the run's play page URL
  --timing         Report read phases and periodic long-read updates to stderr
  -h, --help       display help for command
```

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Explanation:
  Purpose:
    Current status and structure of one run: state, per-step progress, row
    counts, dataset handles, and exact follow-up commands.
  When:
    To check a run started with --no-wait, to find the dataset table name for
    db query, or to see row-level failure counts. Not for cost and not for
    rows.
  Input:
    The run id. --full resolves a full-only result and adds diagnostics with
    billing and timeline (large). --log-failed attaches the failure log window.
    --input prints the original input (may contain customer data). --json
    prints JSON; --json run.status,datasets.name selects fields.
    To parse the output (also with --full), add --json; stdout is then one JSON document.
  Output (JSON):
    kind "run_overview", run {id, playName, status, startedAt, finishedAt,
    durationMs}, steps[] {id, kind, status, label, progress {total, executed,
    reused, failed, completedRows}}, failures.steps[], errorDetails,
    rowOutcomes, warnings[], datasets[] {datasetId, name, rowCount, summary,
    storage {schema, table}, preview {returnedRows, totalRows, partial, rows}},
    result or resultState, and actions holding exact follow-up commands
    (getFullRunCmd, getBillingCmd, getLogsCmd, exportDatasetCmds[],
    queryTableSqlCmds[]). A batch run's payload is tens of kilobytes; read
    run.status and datasets[] and take rows and cost from the narrower
    commands.
  Cost:
    Free.
  Avoid:
    Cost is not in this payload without --full; use billing usage --run-id.
    datasets[].preview.rows is a sample, not the rows; use runs export or db
    query.

  Output fields:
    run.status            queued, running, completed, failed, or stopped. Only
                          the last three are terminal.
    run.activity          the current step while running, null when finished.
    steps[].label         the step's state in one line, as the dashboard shows
                          it.
    datasets[].summary.reportedPopulation  {totalRows, persistedRows,
                          succeededRows, failedRows}. failedRows > 0 means some
                          rows have no result; export them and read the
                          failure columns before reporting.
    datasets[].summary.columnStats  per-column fill and unique counts; a quick
                          fill-rate read without exporting.
    datasets[].storage    {schema, table}: the customer-database table holding
                          the rows; actions.queryTableSqlCmds[] has a ready db
                          query for it.
    datasets[].preview    {returnedRows, totalRows, partial, rows}: a sample
                          for a first look, never an export count.
    resultState           "available_in_full" means the result was left out;
                          --full resolves it.
    rowOutcomes           terminal row accounting: successes, failures and
                          superseded rows are disjoint, and a superseded row
                          belongs to a newer write's latest view. Absent while
                          the run is active. A completed status alone does not
                          mean every input row produced a successful row.
    actions.*Cmd          exact commands: exportDatasetCmds[], getBillingCmd,
                          queryTableSqlCmds[], getLogsCmd, and stopRunCmd while
                          the run is active.
  With --full:
    diagnostics holds the raw status: billing, timeline, errors, child runs.
    --json diagnostics needs --full. Use --full only when a program will read
    it; it is several times larger than the default overview.
  Debugging a run:
    When a run failed or looks stuck, read runs get <run-id> for its state and
    last event, then runs logs <run-id> --failed for the failure window, then
    runs watch <run-id> to follow it if it is still active. A run can go quiet
    for minutes while it waits on a slow provider (Apify actors, large company
    searches), an intentional deepline.sleep, or a rate-limit backoff; that is
    healthy. Stop it only after about ten minutes without progress on a fast
    tool.
```

## runs rerun

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs rerun [options] <runId>

Start a fresh run from a prior run's retained input and pinned revision.

Options:
  --idempotency-key <key>   Reuse this key so repeated calls resolve to one
                            rerun
  --input-overrides <json>  Override existing scalar fields in the retained
                            input for this rerun
  --json                    Emit JSON output
  -h, --help                display help for command
```

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Explanation:
  Purpose:
    Start a new run of the same play with the same input as an earlier run,
    reusing its completed rows.
  When:
    After fixing the cause of a partial failure. When a failed run is
    resumable, runs get also prints the exact command under actions.rerunCmd.
  Input:
    The run id. --json.
  Output (JSON):
    The new run's package, as plays run --json prints.
  Cost:
    Spends credits only for rows that were not completed before.
```

## runs list

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs list [options]

List play runs.

Options:
  --play <name>      Play name to filter runs
  --node <id>        Mermaid node id to filter runs
  --status <status>  Filter by run status
  --limit <count>    Maximum runs to return
  --offset <count>   Zero-based page offset (requires --play)
  --compact          Drop verbose fields from JSON output
  --json             Emit JSON output
  --timing           Report the inventory request duration and periodic
                     long-read updates to stderr
  -h, --help         display help for command
```

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Explanation:
  Purpose:
    Recent runs of a play, or all runs in a status, with per-run credits.
  When:
    To find a previous run id, to check whether a play already ran on the same
    input, or to read per-run spend across several runs.
  Input:
    --play <ref> and/or --status <queued|running|completed|failed|stopped>
    (at least one). --limit, --offset (with --play), --compact, --json.
  Output (JSON):
    runs[] {id, status, playName, createdAtIso, startedAtIso, finishedAtIso,
    billingTotalCredits}, count, total, has_more, next, render.sections (one
    line per run: id, status, start time, credits).
  Cost:
    Free.
  Avoid:
    runs[].id is the public run id that runs get, watch, export and stop
    accept. runId and workflowId are older names for it; temporalRunId is a
    backend identifier and not a run id. Use the id your own run returned:
    the latest entry here may belong to another invocation that started at the
    same time.
```

## runs stop-all

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs stop-all [options]

Stop active play runs in the current workspace.

Options:
  --reason <text>  Reason to include with each stop request
  --dry-run        List the runs that would be stopped without cancelling
                   anything
  --json           Emit JSON output
  -h, --help       display help for command
```

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Explanation:
  Purpose:
    Request cancellation of every active run in the workspace.
  When:
    Unjamming a workspace. Do not use it to stop one run; use runs stop.
  Input:
    --reason "<text>". --dry-run lists what would be stopped. --json.
  Output (JSON):
    The runs that were asked to stop.
  Cost:
    Free.
```

## runs watch

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs watch|tail [options] <runId>

Poll the canonical run snapshot until terminal status.

Options:
  --json               Emit one terminal JSON package after the run completes
  --jsonl              Emit watched events as JSON Lines, then the terminal
                       package
  --compact            Show deduplicated human step transitions and progress
  --log-level <level>  Minimum severity: debug, info (default), warn, or error
  -h, --help           display help for command
```

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Explanation:
  Purpose:
    Follow an active run until it ends, polling its status every two seconds.
  When:
    For a run started with run --timeout 0, or one run stopped waiting for.
    runs get answers "is it done". runs tail is an alias.
  Input:
    The run id. --compact shows step transitions only; --json prints one
    terminal package at the end; --jsonl prints events as JSON Lines.
  Output:
    Progress lines as the run changes, then the same package shape as runs get
    --json.
  Cost:
    Free.
```

## runs logs

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs logs [options] [runId]

Read a run’s logs or search recent events.

Options:
  --limit <count>      Maximum results: logs 200; events 100, max 200
  --out <path>         Save the full available text log
  --failed             Terminal log tail of an overall failed run; completed
                       runs with failed rows use runs events --kind
                       receipt.failed --payloads
  --log-level <level>  debug (default), info, warn or error
  --step <id>          Query structured logs from this authored step
  --level <level>      Query structured logs at this severity or above
  --query <text>       Find literal text in the full retained log message
  --count              Exact matching retained log count; no limit or payloads
  --group-by <fields>  Count log groups by comma-separated fields
  --sum <field>        Count and sum numeric values; repeatable, optionally
                       grouped (default: [])
  --fields             Discover query fields, types and operators
  --json               JSON output
  --since <timestamp>  Search from this UTC time
  --until <timestamp>  Search before this UTC time
  --play <name>        Filter by Play
  --kind <kind>        Filter by event kind
  --where <filter>     Match event fields; examples below
  --payloads           Include available details or saved results
  --cursor <token>     Continue to older logs or the next events page
  -h, --help           display help for command
```

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Explanation:
  Purpose:
    The stored text logs of one run, or a search of recent events across the
    workspace's runs. Nothing runs again.
  When:
    When a run failed and the runs get error is not enough: runs logs
    <run-id> --failed shows the failure window; --out <path> saves the whole
    log. Without a run id it searches events: which runs or steps failed
    (--kind run.failed, --kind step.failed), with --payloads for the details.
    To read what a tool call in a run returned: runs logs <run-id> --kind
    receipt.completed --payloads, then one exact result by its eventId
    with --where.
  Input:
    A run id alone reads text logs; no run id, or any search flag, searches
    events. The flags, event kinds, and --where filter examples are listed
    above.
  Output:
    Log lines (human) or a JSON envelope; with --out, the file path. Follow
    next.logs for the next page of events, and pass nextCursor to --cursor for
    older text logs. To parse the output, add --json; stdout is then one JSON
    document.
  Cost:
    Free.
  Avoid:
    --out, --failed and --log-level apply to text logs and cannot be combined
    with an event search. --where is not SQL: it takes equality tests joined
    with &&.
```

## runs stop

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs stop [options] <runId>

Stop a play run.

Options:
  --reason <text>  Reason to include with the stop request
  --json           Emit JSON output
  -h, --help       display help for command
```

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Explanation:
  Purpose:
    Request cancellation of one active run.
  When:
    A run is stuck, was started by mistake, or was superseded. Runs of the same
    play do not cancel each other: an older run keeps working and keeps
    spending until it ends or is stopped. runs list --play <name> --status
    running lists them. Completed work is kept and reused by a later run of the
    same play and input.
  Input:
    The run id and --reason "<text>". --json prints JSON.
  Output (JSON):
    The run's new status; cancellation is asynchronous, so poll runs get.
  Cost:
    Free, but rows already processed were charged.
```

## runs export

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Usage: deepline runs export [options] <runId>

Export a play run dataset to a CSV or JSON file.

Options:
  --out <path>           Output file path
  --format <format>      File format: csv or json (default: "csv")
  --summary <mode>       Row summary: full or counts (default: full)
  --dataset <path>       Returned dataset handle path, such as result.rows
  --metadata-out <path>  Write export metadata JSON to a file
  --allow-empty          Allow a completed, healthy zero-row dataset
  --wait                 Wait for this run to reach a terminal status before
                         export
  --timeout-ms <ms>      Maximum wait with --wait (default: 300000)
  --json [fields]        JSON receipt; optionally select fields
                         (dataset,datasets,actions). Does not filter exported
                         rows
  -h, --help             display help for command
```

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Explanation:
  Purpose:
    Write a run's result rows to a local CSV file.
  When:
    After a run completes, as the way to get rows. It is also the file to
    show a user.
  Input:
    The run id and --out <path> (required). --format json writes an array of
    rows instead of CSV. --dataset <path> selects a handle when the run
    returned more than one (default: the returned dataset, usually
    result.rows). --metadata-out <path.json> writes the export metadata. --json
    prints the receipt as JSON; it does not change the file format.
    --summary counts keeps exact row counts while skipping column aggregates
    during retrieval; every saved row and column is still exported. The default
    --summary full includes column aggregates.
    To parse the receipt, add --json; stdout is then one JSON document.
  Output (JSON):
    csv_path or json_path (absolute), source, rowCount, columns[] (the CSV
    header), datasets, and actions with follow-up commands. The file includes
    the input columns
    plus the play's output fields (for example email, email_source,
    email_validated, waterfall_attempts) and per-provider attempt columns.
  Cost:
    Free.
  Avoid:
    Do not reconstruct rows from runs get; export is complete and cheap.

  Cases:
    Right after a run finishes, export can report that the backing dataset was
    not ready to export yet and print the command to retry. Run that command
    again, or read the rows with db query meanwhile; never rerun the play, the
    rows are already paid for.
    A run with failed rows exports them too; the output fields for those rows
    are blank and the attempt columns explain why. Report them as unresolved
    rather than dropping them.
    A run that returned no dataset (a single-value play) has nothing to export;
    the result is in runs get under outputs or result.
    --dataset accepts a dataset path such as result.rows; runs get
    actions.exportDatasetCmds[] has the exact line for each dataset.
  Output fields:
    columns[]         the exact header order written; use it to pick columns to
                      show.
    rowCount          rows written, including failed rows.
    local.csv_path    same as csv_path; present for tooling.
```

## Log and event filters

## Query retained logs

`--step`, `--level`, `--query`, `--count`, `--sum`, or `--group-by` select structured logs for one run. Bounds and `--where` filter those log records. `--step` matches the recorded authored step. `--level warn` includes warn and error. `--query` searches the full retained message literally, including percent signs and underscores. `runs events` applies these operations to lifecycle events, receipt events, and events across the organization.

Structured reads default to the last hour and 50 records or groups per page, with a maximum of 200. Records appear newest first, and summary groups use ascending keys. `--count` returns an exact retained count and rejects `--limit`, `--cursor`, and `--payloads`. `--group-by` pages all matching groups, and `--sum` totals numeric fields or returns an ungrouped count and sum without `--group-by`. Numeric sums reject strings and booleans, and groups distinguish missing values from null. The reader cannot reconstruct sampling or expired history.

`--fields` returns fields, types, and operators. `where` accepts scalar equality, `{ eq, ne, gt, gte, lt, lte, in, exists }`, nested `context: { key: ... }`, flat `"context.key"`, and `{ and: [...] }` / `{ or: [...] }`. String predicates accept equality, inequality, ranges, `in`, `exists`, `&&`, `||`, parentheses, and `$.field`. Strings need JSON double quotes, while numbers, booleans, and null remain unquoted. Missing fields do not match comparisons, so use `exists false` for missing values. Filters allow 64 comparisons and 8 KiB, and custom context fields must be recorded scalars rather than nested payload data.

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline runs logs '<run-id>' --step company-lookup --level warn --since 1h --where 'context.attempt >= 2 && context.cached == false'
deepline runs logs '<run-id>' --query 'timeout %_MARKER' --count
deepline runs logs '<run-id>' --group-by stepId --sum context.durationMs
deepline runs logs --fields
deepline runs events --kind step.failed --since 1h
```

`client.runs.logs(runId, options)` remains the text reader. Use `logs.query/count/summarize/fields` for structured logs. Use `client.runs.events.list/count/summarize/fields` for events. Omit `runId` to read across the organization. Each method makes one request per page or aggregate.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { DeeplineClient } from "deepline";
const client = new DeeplineClient();
const runId = "<run-id>";
const page = await client.runs.logs.query(runId, {
  since: "1h",
  stepId: "company-lookup",
  minLevel: "warn",
  where: { context: { cached: false, attempt: { gte: 2 } } },
});
const count = await client.runs.logs.count(runId, page.query);
```

Lists return flat `logs` or `events`, `page: { returnedCount, hasMore, nextCursor }`, frozen `query` criteria, and `retention: { retainedSince, retentionDays }`. Relative bounds resolve once with inclusive `since` and exclusive `until`. Frozen criteria fix the window rather than a snapshot, so newly available events may change later pages or aggregates. Start a fresh list to find late arrivals ahead of its cursor. Follow `next.page` or reuse `query` with `cursor: page.nextCursor` when `hasMore`. Criteria exclude page options and the positional log run ID, retain an event run ID, and preserve SDK Preview selection.

Recorded step, level, source, attempt, and context stay together. Absent historical fields stay absent. Counts return `matchedCount` and `exact: true`. Summaries return `groups`, `groupBy`, `measures`, and an independent `page`, with `keys` and named numeric `measures` in each group. Missing keys use `{ "missing": true }`, distinct from null or `"<missing>"`.

HTTP uses `POST /api/v2/runs/events` with a flat body containing `operation: "list" | "count" | "summarize" | "fields"`, `resource: "logs" | "events"`, `runId`, criteria, and options. Log list, count, and summary requests require `runId`, but field requests do not. Summaries require `groupBy`, with `[]` for an ungrouped aggregate. Summaries accept `measures: [{ op: "count" }, { op: "sum", field: "context.durationMs", as: "durationMs" }]`. The SDK, HTTP API, and CLI use the same filter checks. The existing GET and text-log contracts remain available below.

## Read logs or search events

\--failed reads terminal context only when the overall run failed. A completed run can still contain failed rows: use `runs events <run-id> --kind receipt.failed --payloads --json` and inspect the run dataset. `runs get <run-id> --json` reports row outcome counts.

A run ID alone reads text logs. Use the returned nextCursor with --cursor for older lines. Without a run ID, or with a search flag, the command searches events. A supplied run ID narrows event search. Event search rejects --out, --failed, and --log-level.

Search defaults to the last hour with newest events first and a maximum lookback of seven days. Follow the returned next.logs command for the next page. --payloads adds available event details or saved work results, not dataset rows. Text logs default to 200 lines, while compatibility event search defaults to 100 events (maximum 200), or 10 with payloads and 16 MiB. Check retention warnings. --out saves all available log lines.

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline runs logs '<run-id>'
deepline runs logs '<run-id>' --out run.log
deepline runs logs --kind run.failed
deepline runs logs --play my-play --since 2026-10-06T00:00:00Z --until 2026-10-06T01:00:00Z
```

## Known event kinds

| `--kind` | Meaning |
| - | - |
| `run.created` | Run accepted. |
| `run.started` | Execution started. |
| `run.waiting` | Run waiting. |
| `run.resumed` | Execution resumed. |
| `run.completed` | Run succeeded. |
| `run.failed` | Run failed. |
| `run.cancelled` | Run cancelled. |
| `step.started` | Step started. |
| `step.progress` | Progress update. |
| `step.completed` | Step succeeded. |
| `step.failed` | Step failed. |
| `step.skipped` | Step skipped. |
| `log.appended` | Text log line. |
| `dataset.lifecycle` | Dataset registered, available or failed. |
| `activity.observed` | Provider or workflow activity. |
| `work.counters` | Call, request and rate-limit totals. |
| `receipt.completed` | Saved result or call details. |
| `receipt.failed` | Saved work result: failed. |
| `receipt.skipped` | Saved work result: skipped. |
| `runtime.event` | Other event. |

## Compatibility event search with --where

String fields are eventId, orgId, runId, playName, runtimeScope, kind, status, source, level, stepId, stepKind, datasetId, phase, provider, and operation. producerAttempt is a positive integer, context.\<key> accepts flat string, number, or boolean log fields, and --kind selects run and step outcomes. Filters contain at most eight \$.field == value predicates and 512 bytes, joined with && within single shell quotes. Missing fields do not match, and strings need double quotes while numbers and booleans remain unquoted. OR, ranges, wildcards, and text or payload search are unavailable, and examples need values from your actual events. status is not inferred from kind, and provider/operation match recorded activity.observed events, not every provider call.

Bare `runs logs --where`, `--since`, and `--kind` retain this equality grammar. Text `--failed`, `--out`, and `--log-level` retain their established behavior. Context examples use `deepline.log("Lookup finished", { context: { companyId: "acme_123", attempt: 2, cached: false } })`.

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline runs logs --kind receipt.failed --where '$.status == "failed"' --payloads
deepline runs logs --kind step.failed --where '$.stepId == "company-lookup"' --payloads
deepline runs logs --kind activity.observed --where '$.provider == "apollo" && $.operation == "company_lookup"'
deepline runs logs --kind dataset.lifecycle --where '$.datasetId == "companies" && $.phase == "failed"' --payloads
deepline runs logs --kind log.appended --where '$.context.companyId == "acme_123"'
deepline runs logs --kind log.appended --where '$.context.attempt == 2 && $.context.cached == false'
deepline runs logs '<run-id>' --where '$.stepId == "company-lookup"'
deepline runs logs --kind log.appended --where '$.level == "error" && $.stepId == "company-lookup"' --payloads
```

## Retrieve results

`--payloads` adds `eventPayload` details or saved `payload` results. The response identifies unavailable details. Select an exact returned `eventId` with its original `--since`/`--until` window. Events remain available for seven days, but details may have different retention. Redirecting JSON saves one page, so follow `next.logs` for compatibility search or `next.page` for structured reads. Use `--out run.log` for all text, or `runs export --format json --out results.json` for dataset rows.

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline runs logs '<run-id>' --kind receipt.completed --payloads
deepline runs logs --where '$.eventId == "receipt:5a32ee1a-46cf-4853-b72b-5f1d782ffab4"' --payloads
```

New tool results retain sanitized input under `payload.output.meta.callEvidence.input` and output under `payload.output.toolResponse.rawV2`. `callEvidence.providerRequests` contains observed HTTP requests, response status, and failed response bodies. The result retains successful output once in `toolResponse.rawV2`. Deepline removes credentials and provider billing fields. Multipart, binary, streaming, oversized, or unobserved evidence includes a reason for unavailable details. Older results may have no input evidence.

Find new saved failed-call records with `--kind receipt.completed --where '$.context.callStatus == "failed" && $.context.callKey == "lookup"' --payloads`. Details have `payload.output.kind: "tool_call_evidence"`, `status: "failed"`, `callEvidence` and the original error. `receipt.completed` means Deepline saved the diagnostic. Use `step.failed` for the failure that caused it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.