Generated from CLI help, the runtime event catalog and SDK source JSDoc by
scripts/generate-play-sdk-reference.ts. Do not edit manually.deepline runs logs --help to discover this contract in the installed CLI.
Choose the read
These commands read existing evidence; they do not start a run or execute a provider. Replace <run-id>, <play-name> and other angle-bracket values with identifiers returned by the CLI. Text logs: runs logs <run-id> returns the last 200 retained lines by default. —out writes the full retained stream to a local file. —log-level filters text severity; debug includes all retained levels. —failed reads only a terminal-failed run’s last 20 retained lines and reports retention limitations. Event search: omit the run ID, or add any of —since, —until, —play, —kind, —where, —payloads, —cursor, —runtime-namespace or —runtime-backend. A supplied run ID then narrows the search. —limit and —json alone do not switch a run’s text logs to event search. Text-only flags —out, —failed and —log-level cannot be combined with event search. Current status and returned output selectors: runs get <run-id> —json. Live observation: runs watch <run-id>. Dataset rows: runs export <run-id> —dataset <returned-selector> —out rows.csv. A referenced tool response: runs receipt <run-id> —key <returned-receipt-key> —json. Read each command’s —help for its options.Known event kinds
Search window and pagination
Search defaults to the last hour, newest first. Use explicit ISO UTC —since and —until values for reproducible queries; the maximum lookback is seven days. Default page size is 100 events; —limit accepts 1–200. With —payloads, default and maximum are 10 events, with 16 MiB total payload data. JSON returns events[], returnedCount, since, until, nextCursor and next.logs. Run the returned next.logs command to continue with the same filters and UTC window; nextCursor is opaque. A bounded page or an empty result does not establish whole-run coverage or application health.Fields you can filter with —where
Identity strings: orgId, runId, playName, runtimeScope. These come from authenticated execution state; filters only narrow your authorized organization/runtime. Preview reads require the existing runtime credential and an authorized —runtime-namespace; —runtime-backend selects daytona or modal. Event string: kind. Optional strings: source, stepId, stepKind, status, datasetId, phase, provider, operation. Optional positive integer: producerAttempt. These fields exist only when recorded; inspect a returned event before filtering on an optional field. stepId/stepKind describe recorded step work; datasetId/phase describe dataset lifecycle (registered, available, failed). provider/operation appear on typed provider activity.observed events, not every receipt or provider call. status is the recorded status or activity state when present: run.completed and step.completed do not imply status == “completed”. Select lifecycle outcomes with —kind. context.<key> matches an authored flat scalar log field: string, number or boolean. Context cannot override event identity. Missing fields do not match. —where supports only $.field == literal predicates joined with &&, at most eight predicates and 512 bytes. No OR, ranges, wildcards, nested payload paths or text search. Time uses —since/—until; level and message are not —where fields. Wrap the entire predicate in single shell quotes so $ and && reach the CLI unchanged. Inside it, strings use double quotes; numbers and booleans are unquoted. Types must match: 2 differs from “2”, false differs from “false”. Examples use illustrative recorded values; use your own step IDs, dataset IDs, provider/operation names and authored context. The context examples assume ctx.log recorded companyId: “acme_123”, attempt: 2 and cached: false.What you get back
Search events include eventId, occurredAt, ingestedAt, kind, runId, playName, level and message. The CLI puts indexed fields directly on each events[] entry; SDK/API responses keep them under searchDoc. Log search message is a preview (up to 2,048 characters); use text logs or —out for full retained lines. —payloads adds eventPayload for stored canonical events: lifecycle, step details/errors, activity observations, dataset transitions and work counters. Receipt matches instead hydrate payload with status, output, error and errorPayload. An event without a receipt does not promise a tool response; retained payloads may be unavailable. Neither —where nor event search indexes request/response bodies. Search does not expose a receipt key or storage reference. To retrieve a specific retained tool response with runs receipt, use the receipt key returned in the run’s exported evidence or tool execution metadata. For full row data, follow runs get output/export actions; dataset.lifecycle contains metadata, not all dataset rows. The catalog lists known searchable kinds, including receipt outcomes and the runtime.event fallback. Use the exact dotted name with —kind. Future stored kinds can also be queried; this list is not a CLI validation allowlist. Events are observations, not a count of billed provider calls. Catalog payload fields are possible producer fields, not required fields or —where paths. Canonical eventPayload uses type for the dotted event kind; its kind field, when present on a step, becomes indexed stepKind. Indexed log entries describe individual lines rather than reproducing the original lines batch. Canonical event envelopes carry runId, type, occurredAt (producer milliseconds), source, optional seq and optional producer-owned payload. Search occurredAt/ingestedAt are UTC timestamp strings. source identifies the recorded producer; producerAttempt is present only when known. activity.observed stores observation with activityId, stepId, target, state and observedAt. Targets describe provider, dataset, lease, runner, step or capacity work. State kinds are active, queued, waiting, retrying, scheduled, completed or failed; retry/wait detail stays in the payload. work.counters contains aggregate logicalCalls, providerRequests and provider429s, not per-call responses.Storage and retention
Event/log/receipt search shares the PlanetScale index. New runs marked runEventStore=planet_scale retain accepted event/log history in PlanetScale; Convex keeps current run/control state and eligible saved-Play rollup facts. Older unmarked runs retain their existing readers. No backfill is implied. Search retention is seven days; receipt payload retention is independent. Logs reflect accepted, retained lines: runtime sampling and truncation can omit original console output. Read returned retention/sampling warnings; an export contains the full retained stream, not suppressed lines.SDK and HTTP field contract
client.runs.searchEvents(options) reads GET /api/v2/runs/events. Options map directly to HTTP query parameters except includePayloads → payloads=true; Preview runtime uses the existing runtime credential headers. The SDK resolves default time bounds relative to request time; raw HTTP defaults an omitted since to one hour before until. The response is RunsEventSearchResult. Types and descriptions below are generated from the SDK source JSDoc.