Generated from CLI help, the runtime event catalog and SDK source JSDoc by
scripts/generate-play-sdk-reference.ts. Do not edit manually.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. |