Tasks, runs, attempts, and events
Learn the four records behind every piece of work.
Runlane separates the code you write from each execution of that code. Four terms describe the lifecycle.
Task: the reusable definition
A task is application code with a stable id, an input schema, and a handler. It can also define an output schema, queue, retry policy, idempotency or singleton keys, concurrency key, and schedules.
Registering a task makes it available to the runtimes that trigger and execute it.
Run: one durable request
A run is one stored request to execute a task. It has its own id, validated payload, queue, status, timing, counters, source, keys, output, and failure.
The payload is the input schema's validated output. Attempts reuse it without repeating input validation or transformations. Runlane does not retain a separate copy of the original input.
Triggering the same task twice normally creates two runs. An idempotency key can return an existing owner instead, and a singleton key can prevent overlapping work.
The run record is the easiest way to read current state. A successful handler's JSON result is stored on run.output. undefined means a successful task with no output; null remains an explicit null result.
Attempt: one execution try
An attempt starts when a worker claims the run and calls its handler. A failure may lead to a retry. An expected wait may release the run. Worker recovery can also make it eligible again.
Each later attempt starts the handler from the beginning with the persisted payload and context. Runlane does not capture a JavaScript continuation. Completed durable steps can return saved output, but ordinary local variables are gone.
Event: one accepted change
An event records an accepted lifecycle change, such as creation, delivery request, claim, start, retry, release, cancellation, or completion. Events are ordered within one run. Their sequence does not create a global order across the environment.
Storage appends the event and updates the current run record under optimistic sequence control. The run shows where the work is now; its events explain how it got there.
Token: a durable external decision
A token is not a run. It is a durable coordination record for one external result, such as an approval. A token can be pending, completed, or timed_out, and it keeps its terminal result separately from the runs waiting on it.
Use define and trigger tasks to create work. Use observe and recover runs to inspect its current state and history.