Runs and waits

These APIs belong to the runtime returned by createRunlane(). Import their types and enums from @runlane/core. All operations use that runtime's environment.

Read runs

Call	Return value and behavior
`runs.get(runId)`	`Promise<RunRecord \| undefined>`. Reads a run with its payload, status, and stored result.
`runs.get(task, runId)`	A promise of a typed run or `undefined`. Requires a task with an output schema. Validates successful output and checks that the run belongs to that task.
`runs.list(options?)`	`Promise<Page<RunSummary>>`. Returns one page of run summaries.
`runs.events(runId, options?)`	`Promise<Page<RunEventRecord>>`. Returns one page of the run's event history.
`runs.attempts(runId)`	`Promise<readonly RunAttemptSummary[]>`. Reads the run's history and groups it into attempts. This can read multiple event pages.
`runs.findActive({ task, idempotencyKey?, singletonKey? })`	`Promise<RunRecord \| undefined>`. Finds an active run. Supply at least one key.
`runs.findCurrent({ task, idempotencyKey })`	`Promise<RunRecord \| undefined>`. Finds the current key owner, including a retained terminal run.

A run can be scheduled, queued, running, retrying, released, cancellation_requested, succeeded, failed, or cancelled. Use the matching RunStatus enum member in TypeScript. Terminal runs have finished: succeeded, failed, or cancelled. A run timeout is a failure with code TaskTimedOut; timed_out is a wait token status.

Check for undefined before reading a result. Check RunStatus.Succeeded before using successful output. A typed read can throw ValidationFailed for the wrong task or TaskOutputInvalid if retained output no longer matches the task schema.

findActive() needs a lane with operator read support. See choose a lane for supported capabilities.

Run filters and pagination

ListRunsOptions accepts these optional fields:

Field	Type
`queues`	`readonly QueueDefinition[]`
`statuses`	`readonly RunStatus[]`
`taskIds`	`readonly TaskId[]`
`idempotencyKey`, `singletonKey`	String keys
`sourceRunId`	Run ID of the source run
`createdAt`, `updatedAt`, `runAt`	Time ranges: `{ from?: Date, to?: Date }`
`sortBy`	`RunSortField`
`sortDirection`	`SortDirection.Asc` or `SortDirection.Desc`
`cursor`	Cursor string returned by the previous page
`limit`	Positive integer page size

Time range endpoints are inclusive. If both are set, from must not be later than to.

ListRunEventsOptions accepts cursor, limit, sortDirection, occurredAt (a time range), types: readonly RunEventType[], and sortBy: RunEventSortField. Every field is optional.

Lists return { data, nextCursor? }. Continue with nextCursor and the same filters and sort order. Stop when it is absent. Read default limits and sort order from defaults.

Control runs

Call	Return value and behavior
`runs.cancel(runId, options?)`	`Promise<RunRecord>`. Cancels waiting work or requests cooperative cancellation of a running attempt.
`runs.retry(runId, options?)`	`Promise<RunRecord>`. Creates a new linked run from a failed run. Leaves the original unchanged.
`runs.rerun(runId, options?)`	`Promise<RunRecord>`. Creates a new linked run from a terminal run. Leaves the original unchanged.
`runs.prune(options)`	`Promise<PruneRunsResult>`, containing `prunedCount` and optional `nextCursor`. Removes eligible terminal runs from normal reads.
`idempotencyKeys.reset(task, { key })`	`Promise<void>`. Clears a retained idempotency key so a later trigger can create a new run.

CancelRunOptions accepts optional actor, meta: JsonObject, traceCarrier, and reason: string.

Retry and rerun accept CreateLinkedRunOptions: optional actor, meta, traceCarrier, queue: QueueDefinition, and runId. They are explicit operator actions, separate from a task's automatic retry policy.

Cancellation does not force JavaScript to stop. The handler must cooperate through context.signal or context.isCancellationRequested(). See cancel runs and retry and rerun runs.

PruneRunsOptions requires olderThan: Date | DurationString. Optional fields are actor, cursor, limit, and a nonempty list of terminal statuses. Follow its cursor to process more eligible runs. Related stored data can require later cleanup passes. See prune old runs before setting a retention policy.

Reset rejects with StorageConflict while the key's owner is active. It does not cancel that run. See prevent duplicate runs for reset rules and key retention.

Signals

signals.send(signalKey, { limit? }) returns Promise<readonly RunRecord[]>. The result contains only the runs this call successfully resumed.

signalKey is a nonempty string. limit is an optional positive integer; its default is contractDefaults.maintenance.deliveryRequestLimit. Each call scans one bounded batch. Send again if more current waiters may remain.

A signal wakes runs already waiting on that key. It does not save a value or keep a message for future waiters. Save the application state first, then send the signal. A timeout lets a waiting task recheck state if it misses the signal. See wait without failing.

Wait tokens

Tokens store one external result and an optional fixed deadline. Their status is WaitTokenStatus.Pending, WaitTokenStatus.Completed, or WaitTokenStatus.TimedOut.

Call	Return value and behavior
`wait.createToken(options?)`	`Promise<CreateWaitTokenResult>`, containing `outcome` and `token`. Outcome is `created` or `returned_existing`.
`wait.getToken(tokenId)`	`Promise<WaitTokenRecord \| undefined>`. Returns stored JSON output on a completed token.
`wait.completeToken(tokenId, options)`	`Promise<CompleteWaitTokenResult>`, containing `outcome` and `token`. Outcome is `completed`, `timed_out`, or `already_resolved`.
`wait.listTokens(options?)`	`Promise<Page<WaitTokenSummary>>`. Summaries omit output, metadata, and the completion actor.
`wait.pruneTokens(options)`	`Promise<PruneWaitTokensResult>`, containing `prunedCount` and optional `nextCursor`. Prunes eligible terminal tokens with no retained run links.

Create a token

CreateWaitTokenOptions has only optional fields:

Field	Type and behavior
`timeout`	`DurationString`. Sets a fixed deadline when the token is created. Omit it for no deadline.
`idempotencyKey`	String key that reuses a token in the same environment. Use a stable key when creation may repeat.
`idempotencyKeyTTL`	`DurationString`. Requires a key. Unlike task keys, token keys do not accept `IdempotencyKeyTTLMode.Active`.
`meta`	`JsonObject` describing the token.

If creation returns an existing token, read its current status. It may already be completed or timed out. Without a key TTL, ownership remains until pruning removes the token.

Complete and read a token

CompleteWaitTokenOptions requires output: JsonValue. Optional actor and meta: JsonObject record who completed it and why. Authenticate and authorize the caller in your application before completing a token.

The first terminal result wins. Completion after the deadline can return timed_out. Repeating a completion can return already_resolved; it does not replace the stored output. Always use the returned token to decide what happened.

The runtime's wait.getToken() returns raw JSON. Inside a handler, context.wait.getToken(tokenId, { output: schema }) validates a completed result. Return context.wait.forToken(tokenId) while it is pending. Maintenance resumes waiting runs after the token resolves.

List and prune tokens

ListWaitTokensOptions accepts optional createdAt: { from?: Date, to?: Date }, cursor, limit, sortDirection, and one status: WaitTokenStatus.

PruneWaitTokensOptions requires olderThan: Date | DurationString, with optional cursor and limit. Pending tokens and tokens still linked to retained runs are not eligible.

See build a human-in-the-loop flow for a complete task and completion service.

On this page