Skip to main content
POST
Submit a task

Authorizations

Authorization
string
header
required

A team API key, sk_offstage_…, created in the console. Everything it touches belongs to its team.

Headers

Idempotency-Key
string

Any unique string. A retry with the same key and body within 24 hours answers 201 with what the first request made, as it is now, instead of creating again, including after a plane restart; the same key with a different body is 409 idempotency-key-reused. Failures are not remembered. Scoped to the team and the route.

Required string length: 1 - 255

Body

application/json

Unknown fields are refused with 400 unknown-field.

repo
string
required

The https:// clone URL of a public repository, with no credentials in it. The URL is stored and shown on the task.

Required string length: 1 - 2048
kind
enum<string>
required

Labels the task and picks its default session: screenshot runs gui, the rest headless. agent runs agent instead of command. (runner tasks come from GitHub, never from this call.)

Available options:
build,
test,
screenshot,
agent
command
string

The shell command line to run in the clone. Required for every kind except agent, which must not have one. Stored and shown on the task, so never put a secret in it. There is no env, ref or branch field: put them in the command.

Minimum string length: 1
agent
string

Only for kind: agent, and required there: the agent program the slot runs.

Minimum string length: 1
artifacts
string[]

File names in the clone's root that the task promises to upload; nothing else is kept. A name is 1 to 128 letters, digits, ., _ and -, starts with a letter or digit, has no .. and does not end in .meta.json. If the command exits 0, every promised artifact must exist and be non-empty. One artifact is at most 100 MiB, a task's together at most 256 MiB, and a team's stored artifacts at most 512 MiB; past any of those, or when the plane's artifact storage is full, the upload is refused with 413 artifact-quota, whose message names the share. Artifacts are deleted 7 days after their task ends.

Maximum array length: 32
Pattern: ^(?!.*\.\.)(?!.*\.meta\.json$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$
session
enum<string>

Defaults by kind: gui for screenshot, headless otherwise.

Available options:
headless,
gui
timeoutMs
integer
default:1800000

Wall-clock cap on the whole task, clone included. 30 minutes by default.

Required range: 1 <= x <= 86400000
queueTimeoutMs
integer
default:900000

How long it may wait for a slot before failing with failureReason: no-capacity. 15 minutes by default. A team runs 4 tasks at once, and time spent behind the team's own earlier tasks while it has those 4 running does not count: the wait counts from the last moment the team held it back.

Required range: 1 <= x <= 86400000
record
boolean

Record a gui task's screen while it runs: pictures every few seconds and its log, playable after its slot is reset. Default true for gui.

secrets
string[]

Existing team names. Encoded selected payload at most120 KiB; at most one apple-signing bundle.

Required array length: 1 - 16 elements
Pattern: ^[A-Za-z_][A-Za-z0-9_-]{0,63}$

Response

The task, in state queued. A replay of an earlier create with the same Idempotency-Key and body answers 201 with that task as it is now (the same id, in its current state), with idempotent-replayed: true.

A task. Fields that do not apply yet (boxId, slot, startedAt, endedAt, runtimeSeconds) are absent, not null.

id
string
required

task_….

Pattern: ^task_
spec
object
required

The task as submitted, with defaults filled in.

state
enum<string>
required

queued → claimed → running → succeeded | failed | timed_out, or cancelled from any state before those. The last four are terminal.

Available options:
queued,
claimed,
running,
succeeded,
failed,
timed_out,
cancelled
createdAt
integer
required

A time, in Unix milliseconds.

Required range: x >= 0
attempts
integer
required

How many slots claimed it and never started it.

Required range: x >= 0
requeued
boolean
required

True once a slot claimed it and never started it, so it went back to queued.

costUsd
number
required

What its running time costs: accrued so far while it runs, final once it ends. 0 for work the fleet lost.

createdBy
object
required

Who started the work: {keyName} for an API key, {email} for a console user.

exitCode
integer | null
required

The command's exit status once the Mac reports it; null before then, and when there was none (timed out, cancelled, lost).

droppedLogLines
integer
required

Log lines dropped from the front to keep the last 500.

Required range: x >= 0
failureReason
enum<string> | null
required

Why it ended failed or timed_out; null in every other state.

Available options:
exit,
setup,
timeout,
no-capacity,
box-lost,
plane-restart,
never-started
events
object[]
required

The whole story, in order. The log keeps its last 500 lines; when lines were dropped, the first log event says how many.

boxId
string

The Mac that holds or ran it. Absent until a slot claims it.

Pattern: ^box_
slot
integer

The slot on that Mac. Absent until claimed.

Required range: x >= 1
startedAt
integer

When the command started. Absent until then.

Required range: x >= 0
endedAt
integer

When it ended. Absent until then (and for a queued task that was cancelled).

Required range: x >= 0
runtimeSeconds
integer

Whole seconds from start to end. Absent until it ends.

Required range: x >= 0
github
object

Only on a runner task: the GitHub Actions job it was made for.

replayUrl
string

Where to watch it, live while it runs and as a replay after: the console's /r/{id} page. Present for a gui task that records.