Run logs and events

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.

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.

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.

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 } }).

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.

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.

​Query retained logs

​Read logs or search events

​Known event kinds

​Compatibility event search with —where

​Retrieve results

​SDK and HTTP field contract

Query retained logs

Read logs or search events

Known event kinds

Compatibility event search with —where

Retrieve results

SDK and HTTP field contract