Runs

A run is created when you trigger a task. It represents a single instance of task execution.

Run Lifecycle

Initial States

State	Description
PENDING_VERSION	Waiting for a version update
DELAYED	Triggered with delay, waiting
QUEUED	Ready, waiting in queue
DEQUEUED	Being sent to worker

Execution States

State	Description
EXECUTING	Currently running
WAITING	Paused (triggerAndWait, wait.for, etc.) — does NOT count against concurrency

Final States

State	Description
COMPLETED	Successfully finished
CANCELED	Manually canceled
FAILED	Error after all retries
TIMED_OUT	Exceeded maxDuration
CRASHED	Worker crashed (OOM)
SYSTEM_FAILURE	Unrecoverable system error
EXPIRED	TTL passed before execution

Attempts

Each run can have one or more attempts (based on retry settings). Each attempt has:

• Unique attempt ID
• Status
• Output (success) or error (failure)

Boolean Helpers

const run = await runs.retrieve("run_1234");

run.isQueued     // QUEUED, PENDING_VERSION, or DELAYED
run.isExecuting  // EXECUTING or DEQUEUED (counts against concurrency)
run.isWaiting    // WAITING (does NOT count against concurrency)
run.isCompleted  // Any completed status
run.isCanceled   // CANCELED
run.isFailed     // Any failed status
run.isSuccess    // COMPLETED

Runs API

runs.list()

// Paginated
let page = await runs.list({ limit: 20 });
for (const run of page.data) { console.log(run); }

// Async iterator (auto-paginate)
for await (const run of runs.list({ limit: 20 })) { console.log(run); }

Available filters: status, taskIdentifier, from, to, version, tag, batch, schedule.

runs.retrieve()

// Fully typed when passing task type
const run = await runs.retrieve<typeof myTask>(runId);
console.log(run.payload.foo); // typed payload
console.log(run.output.bar);  // typed output

runs.cancel()

await runs.cancel(runId);

runs.replay()

await runs.replay(runId);

Creates a new run locked to the current version (not the original version).

runs.reschedule()

await runs.reschedule(runId, { delay: "1h" });

Real-time Updates

Subscribe to a run and get updates as it progresses:

for await (const run of runs.subscribeToRun<typeof myTask>(runId)) {
  console.log("Run status:", run.status);
  if (run.isCompleted) { break; }
}

Advanced Features

• Idempotency Keys — prevent duplicate executions
• TTL — auto-expire runs that don't start in time (dev runs default to 10 min)
• Delayed runs — schedule runs to start after a delay
• Undeployed tasks — runs enter "Waiting for deploy" state until task is deployed