Executions

One invocation of a built handler — the durable record of what was sent in, which build answered, and how it ended.

v1stablebilled

Creating one

POST /v1/executions takes an app_id and an input of any shape, and returns 202 with the execution already pinned to the build the app is on. A worker picks it up on its own clock; the record holds the request in between.

environment_idis optional: it names the variable group the process starts under, and must belong to the app's own project. Leave it out and the handler runs with none. mode is optional too — run unless you ask for serve.

shell

curl -sS -i -X POST \
  $NEURUN_URL/v1/executions \
  -H "authorization: Bearer $NEURUN_KEY" \
  -d '{"app_id":"app_01HXQ8F2K9",
       "environment_id":"env_01HXR3W7QP",
       "input":{"url":"https://example.com"}}'

HTTP/1.1 202 Accepted

States

queued → running → succeeded or failed. Use the lowercase API values verbatim. An unrecognised value is rendered neutrally with its raw text — never guessed into success, never allowed to crash a route.

queued: Accepted and waiting for a worker. Holding no compute, and billed for none.
running: Claimed by a worker. The clock that bills you starts here.
succeeded: Terminal. Output and logs are settled and addressable.
failed: Terminal. Carries a failure code and message alongside whatever logs were written.

Claiming is safe under concurrency

A claim takes the oldest queued row with FOR UPDATE SKIP LOCKED, so several workers drain the queue without colliding. Finalizing is a compare-and-set: only a running execution may go terminal, so a late write from a worker that lost its lease loses.

Executions a crashed worker left running are marked failed with worker_restarted on the next start. They are never re-run for you — rerunning is your decision, because only you know whether the handler is safe to repeat.

Pinned to a build

An execution is pinned to the build that was ready when it was created, and never moves. Ten rebuilds later it still names the code that ran. That pinning is the whole reason provenance is legible here rather than reconstructed from deploy timestamps.

Rerun

POST /v1/executions/{execution_id}/rerun repeats the same input against the same build, and refuses if that build is no longer ready rather than quietly running a newer one. The new execution records rerun_of_execution_id, so the pair stays legible.

What is metered

Memory reserved multiplied by wall time, from the moment a worker claims the execution to the moment it goes terminal. Queued time is not billed. Builds are not billed. A rerun costs whatever it consumes, like any other execution.

A server is metered the same way and by the same clock, which is the point of it being an execution: it is claimed once and stays running, so what it costs is the time it was up. See Servers.