Operator Reads
Stable filters, result shapes, sort fields, and cursor vocabulary for operator read APIs.
Operator read vocabulary appears in runlane.runs reads, storage listRuns() / listRunEvents() queries, and cursor-backed continuation tokens. Runtime APIs validate public options and inject the current environment; storage adapters own indexes, cursor encoding, and stable ordering.
Cursor strings are opaque to callers. A storage adapter may encode filter and sort state inside the cursor, but callers should only pass the whole nextCursor token back to the same API with the same logical request.
Runtime APIs
| API | Storage contract | Return shape |
|---|---|---|
runlane.runs.get(runId) | getRun({ environment, runId }) | RunRecord or undefined |
runlane.runs.list(options) | listRuns({ filter, pagination }) | Page<RunSummary> |
runlane.runs.events(runId, options) | listRunEvents({ filter, pagination }) | Page<RunEventRecord> |
runlane.runs.attempts(runId) | Paged listRunEvents() with RunEventSortField.Sequence and SortDirection.Asc | readonly RunAttemptSummary[] |
runlane.runs.findActive(options) | listRuns() over active statuses and task/key filters, then getRun() for the selected match | RunRecord or undefined |
runlane.runs.findCurrent(options) | getRunByIdempotencyKey() | RunRecord or undefined |
Page<T> always returns data: readonly T[] and may return nextCursor. PaginationParams.limit is optional and should be clamped by storage using contractDefaults.pagination; PaginationParams.cursor is the opaque continuation token from the previous page.
RunFilter
RunFilter is the storage-facing filter for listRuns(). Runtime ListRunsOptions uses the same public knobs except that environment is injected and public queues are registered queue definitions that core resolves to queue names before storage sees them.
| Field | Meaning |
|---|---|
environment | Required storage scope. Runtime injects the current environment. |
statuses | Include only matching RunStatus values. |
taskIds | Include only matching task ids. |
queues | Include only matching queue names. |
createdAt | Inclusive { from?, to? } bounds over run creation time. |
updatedAt | Inclusive { from?, to? } bounds over materialized run update time. |
runAt | Inclusive { from?, to? } bounds over the persisted run.runAt value. Runs without runAt match only when no runAt range is supplied. |
idempotencyKey | Include runs that captured this idempotency key. |
singletonKey | Include runs that captured this singleton key. |
sourceRunId | Include linked children created from the source run. |
sortBy | Stable run sort field. Defaults to contractDefaults.sort.runs.field. |
sortDirection | Stable run sort direction. Defaults to contractDefaults.sort.runs.direction. |
RunEventFilter
RunEventFilter is the storage-facing filter for listRunEvents(). Runtime runlane.runs.events(runId, options) always supplies runId; direct storage callers may omit it only when using globally meaningful event ordering.
| Field | Meaning |
|---|---|
environment | Required storage scope. Runtime injects the current environment. |
runId | Restricts results to one run's append-only history. Required when sorting by sequence. |
types | Include only matching RunEventType values. |
occurredAt | Inclusive { from?, to? } bounds over event occurrence time. |
sortBy | Stable event sort field. Defaults to contractDefaults.sort.runEvents.field. |
sortDirection | Stable event sort direction. Defaults to contractDefaults.sort.runEvents.direction. |
SortDirection
| Enum | Value | Meaning |
|---|---|---|
SortDirection.Asc | asc | Return oldest or lowest sort values first. |
SortDirection.Desc | desc | Return newest or highest sort values first. |
RunSortField
| Enum | Value | Meaning |
|---|---|---|
RunSortField.CreatedAt | created_at | Sort runs by creation time. This is the default run-list field. |
RunSortField.RunAt | run_at | Sort runs by next runnable availability, using the same policy as getRunRunnableAvailableAt({ run }). Runs with no runnable time sort after runs that have one. |
RunSortField.UpdatedAt | updated_at | Sort runs by last materialized update time. |
RunSortField.RunAt is not the same as the runAt filter. The filter checks the persisted run.runAt field; the sort key uses runnable availability so queued runs without runAt sort by updatedAt, waiting runs sort by runAt, and running runs sort by lease expiry.
RunEventSortField
| Enum | Value | Meaning |
|---|---|---|
RunEventSortField.OccurredAt | occurred_at | Sort events by occurrence time. This is the default event-list field. |
RunEventSortField.Sequence | sequence | Sort events by per-run sequence. Only use with a runId filter because sequences are monotonic inside one run, not globally. |
Result Shapes
RunSummary is the compact shape returned by run lists. It includes id, environment, taskId, queue, status, counters, createdAt, and updatedAt, plus optional runAt, startedAt, finishedAt, failure, and source. It intentionally omits payloads, leases, trace carriers, metadata, idempotency keys, singleton keys, concurrency keys, and dispatch reservation fields.
RunEventRecord is the append-only history record returned by event lists. It includes the storage-assigned event id, the per-run sequence, and the typed event payload. Event sequences are stable inside one run; cross-run event lists should use occurrence-time ordering.
RunAttemptSummary is derived by runlane.runs.attempts(runId) from replayed run events. It is not persisted separately.
| Field | Meaning |
|---|---|
attempt | Attempt number from execution events. |
startedAt | Start time derived from run.started.occurredAt. |
status | Derived RunAttemptStatus. See Run lifecycle. |
completedAt | Outcome event time for succeeded, failed, retrying, released, or cancelled attempts. |
failure | Failure summary from run.failed or run.retry_scheduled. |
retry | Retry delay and retryAt from run.retry_scheduled. |
release | Release delay, optional reason, and resumeAt from run.released. |
Only run.started creates an attempt summary. run.succeeded, run.failed, run.retry_scheduled, and run.released complete the matching attempt. run.cancelled marks the latest running attempt cancelled; cancelling queued, released, retrying, or scheduled work without a started attempt does not create an attempt row.
PaginationCursorKind
First-party storage adapters use these values inside opaque cursor payloads. Callers must still treat cursor strings as whole tokens and never parse them.
| Enum | Value | Meaning |
|---|---|---|
PaginationCursorKind.RunList | run_list | Cursor for operator run summary pages. |
PaginationCursorKind.RunEventList | run_event_list | Cursor for run event history pages. |
PaginationCursorKind.RunPrune | run_prune | Cursor for terminal run pruning progress. |