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

# Run logs and events

> Read run logs, find failures, filter events and retrieve saved results.

> [!NOTE]
>
> Generated from CLI help, the runtime event catalog and SDK source JSDoc by
> `scripts/generate-play-sdk-reference.ts`. Do not edit manually.

## 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 `ctx.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.

## SDK and HTTP field contract

`client.runs.searchEvents(options)` calls `GET /api/v2/runs/events` and returns `RunsEventSearchResult`. Options map to query parameters, except `includePayloads` maps to `payloads=true`. Preview `runtime` uses runtime credentials. Raw HTTP defaults `since` to one hour before `until`.

| Type | Field | Value type | Required | Contract |
| - | - | - | - | - |
| `RunsEventSearchOptions` | `since` | `string` | No | Inclusive UTC timestamp. Defaults to one hour before the request. |
| `RunsEventSearchOptions` | `until` | `string` | No | Exclusive UTC timestamp. Defaults to the request time. A window spans at most seven days. event retention is seven days. |
| `RunsEventSearchOptions` | `runId` | `string` | No | Optional run filter. Omit to search across the active organization. |
| `RunsEventSearchOptions` | `playName` | `string` | No | Exact Play name. HTTP query parameter `playName`, CLI `--play`. |
| `RunsEventSearchOptions` | `kind` | `string` | No | Exact dotted event kind, such as `step.failed`. The catalog is discoverable with `runs logs --help`. future stored kinds are accepted too. |
| `RunsEventSearchOptions` | `jsonpath` | `string` | No | JSONPath equality joined with `&&`, at most eight predicates and 512 bytes. `eventId` selects an exact returned event. add `payloads` to retrieve its saved details. See `runs logs --help` for fields and examples. Missing fields do not match. status is not inferred from kind. HTTP `jsonpath`, CLI `--where`. |
| `RunsEventSearchOptions` | `includePayloads` | `boolean` | No | Include available `eventPayload` details and receipt `payload` results. maximum ten events and 16 MiB. HTTP `payloads=true`, CLI `--payloads`. |
| `RunsEventSearchOptions` | `limit` | `number` | No | Page size: default 100, maximum 200. with payloads, default and maximum ten. |
| `RunsEventSearchOptions` | `cursor` | `string` | No | Opaque `nextCursor` from the preceding page. Reuse that page's returned since/until and the same filters and runtime scope. |
| `RunsEventSearchOptions` | `runtime` | `PlayRuntimeSelection` | No | Explicit Preview selection requires the existing runtime credential. |
| `RunsEventSearchEntry` | `eventId` | `string` | Yes | Stable event identity. also breaks ties in newest-first pagination. |
| `RunsEventSearchEntry` | `occurredAt` | `string` | Yes | Producer occurrence time as a UTC timestamp string. |
| `RunsEventSearchEntry` | `ingestedAt` | `string` | Yes | Index ingestion time as a UTC timestamp string. may be later than occurrence. |
| `RunsEventSearchEntry` | `runId` | `string` | Yes | Public run identity associated with this observation. |
| `RunsEventSearchEntry` | `playName` | `string` | Yes | Recorded Play name. |
| `RunsEventSearchEntry` | `kind` | `string` | Yes | Exact dotted event kind, such as `step.failed`. |
| `RunsEventSearchEntry` | `level` | `string \| null` | Yes | Recorded log severity, or null on older events. Filter with `$.level == "error"`. |
| `RunsEventSearchEntry` | `message` | `string \| null` | Yes | Log message preview of at most 2,048 characters, or null. Use text logs/export for the full retained line. |
| `RunsEventSearchEntry` | `searchDoc` | `Record<string, unknown>` | Yes | Recorded filter fields. SDK/API keep this nested. The CLI places these fields directly on each event. |
| `RunsEventSearchEntry` | `eventPayload` | `Record<string, unknown>` | No | Available event details when requested with `includePayloads`. dataset events contain metadata, not dataset rows. |
| `RunsEventSearchEntry` | `payload` | `RunsEventPayload \| null` | No | Retained work result for a receipt match when payloads are requested. null if unavailable. Other events need not carry this field. |
| `RunsEventSearchResult` | `events` | `RunsEventSearchEntry[]` | Yes | Matching observations in descending occurredAt/eventId order. |
| `RunsEventSearchResult` | `nextCursor` | `string \| null` | Yes | Opaque continuation token, or null when no further page exists. |
| `RunsEventSearchResult` | `since` | `string` | Yes | Resolved inclusive UTC bound, including a defaulted bound. |
| `RunsEventSearchResult` | `until` | `string` | Yes | Resolved exclusive UTC bound, including a defaulted bound. |
| `RunsEventPayload` | `status` | `'completed' \| 'failed' \| 'skipped'` | Yes | Recorded terminal work outcome. |
| `RunsEventPayload` | `output` | `unknown \| null` | Yes | Saved result, including available sanitized call input/output details. failed-call records use kind: tool\_call\_evidence. Null when no output was retained. |
| `RunsEventPayload` | `error` | `string \| null` | Yes | Stored failure message, or null when absent. |
| `RunsEventPayload` | `errorPayload` | `unknown \| null` | Yes | Stored structured failure details, or null when absent. |


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