12 routes of the published API contract, generated from it.
Auth: API key
Destroy a preserved failure now. The bytes are deleted before the answer says so.
Auth: API key
List your org's runs, newest first. Pages are ?limit=N (1..=500, default 50) and ?cursor=; echo back next_cursor and stop when it is null.
?cursor= for the next page; null on the last one.Auth: API key
Fork N sandboxes from one snapshot, optionally running a command in each. Refused with 409 cap_exceeded before anything starts if the quote exceeds spend_cap. ?wait_ms=N parks until the sandboxes are ready; honours Idempotency-Key.
Idempotent-Replayed: true. The same key with a different request is refused with 409 idempotency_key_reused. A repeat that arrives while the first is still running waits for its answer, or gets 409 idempotency_key_in_use with Retry-After. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make.grade.output in the run report. Never a held-out grader's. Absent: the setting of the snapshot's default grader when the run uses it, otherwise off. Needs a grader (grade, or the snapshot's default).alias@commit7, or promigence/base.Idempotency-Key that was seen before, and no second run was started.idempotent_replay is true: how many seconds ago that first answer was given, so a client can say which earlier request this repeats.count only with allow_partial, and the reason is in warnings.max_cost = Σ sandbox_count × seconds_per_sandbox × per_second_usd, where per_second_usd = vcpus × vcpu_second_usd + mem_gib × gib_second_usd. The most the run can cost if every sandbox runs its whole timeout; billing is for the seconds actually used.GET /v1/runs/{id} and the report give it: "" for the built-in base. Never null from this API; typed nullable for older answers."running".Auth: API key
One run and its sandboxes. ?wait_ms=N long-polls until the run is finished, or every sandbox has ended or outlived its command (kill_on_exit: false, command_outcome set).
GET /v1/runs/{id}: whether the waiting sandboxes can start, so a client that is already long-polling this route does not need a second call to find out why it is waiting.on_failure | off | always. Stated on every answer, so nobody has to remember what the default was.GET /v1/runs/{id}.null while the run is still going.grade_output). Absent when it does not."egress" / "none" stay strings, an allowlist comes back as the object you sent, normalised.POST /v1/runs/quote answers with, without the per-line breakdown: a run that exists has one line.GET /v1/runs/{id}: one compact row per sandbox. The full records, with their timings, are GET /v1/runs/{id}/sandboxes.queued | running | completed | aborted.Auth: API key
Cancel the queue and kill every live sandbox of the run.
Auth: API key
Stop what is still queued. Live sandboxes keep running — use DELETE /v1/runs/:id for those.
Auth: API key
What is preserved of this run's failures, and when each goes.
Auth: API key
Reopen a preserved failure as a new, live sandbox — the state the sandbox was in when it broke, not a re-run from the start. It has its own id and its own billing clock, out of what is left of the run's cap.
Idempotent-Replayed: true. The same key with a different request is refused with 409 idempotency_key_reused. A repeat that arrives while the first is still running waits for its answer, or gets 409 idempotency_key_in_use with Retry-After. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make."ready".Auth: API key
Re-fork the sandboxes whose outcome was an environment failure. Each replay is a new sandbox row with replay_of set, billed like any other sandbox; what the failed original is billed is in the run's report (cost), and a failure our side shows was ours is credited back.
Idempotent-Replayed: true. The same key with a different request is refused with 409 idempotency_key_reused. A repeat that arrives while the first is still running waits for its answer, or gets 409 idempotency_key_in_use with Retry-After. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make.Auth: API key
The validity report: every sandbox, its outcome, and whether the failure was the environment's or the task's. Run through your project's secret redactor before it is serialised.
max_cost = Σ sandbox_count × seconds_per_sandbox × per_second_usd, where per_second_usd = vcpus × vcpu_second_usd + mem_gib × gib_second_usd. The most the run can cost if every sandbox runs its whole timeout; billing is for the seconds actually used.Auth: API key
Only the sandboxes of a run. ?wait_ms=N long-polls until nothing is queued any more.
ok — nothing is waiting; arriving — sandboxes are waiting and should start within eta_s; blocked — they cannot start now, and the reason is named. A block is a refusal, and it arrives at once rather than after a countdown.Auth: API key
Price a run without starting one. No side effects, nothing reserved. Matched ahead of /v1/runs/:id, so a run can never be named quote.
per_second.null when the organisation is not on a trial.max_cost does not cover it. null when the organisation's plan could not be read.POST /v1/runs and the report echo back.ceil(timeout_ms / 1000): what one full sandbox may bill.null for a snapshot this service holds no record of.POST /v1/runs refuse this, said now.