Runs

A run is one execution of an agent. The API records runs but never executes them: assigning a task, waking an agent or triggering a routine puts a run in the queue, and a runner such as sat runner claims it, executes it with Claude Code or Codex, streams the transcript back and reports tokens and cost. Runs are how work happens and how money is spent, so every budget, cost report and "live runs" view is built from them.

How it worksCopy Anchor Link

What queues a runCopy Anchor Link

A heartbeat wake from sat scheduler start sends {"reason": "heartbeat"}, so you can tell it apart from a person's wake only by that first system transcript entry. There is no separate heartbeat trigger value.

Queue dedupe. Before creating a run, the API looks for a run that is still queued for the same agent with the same task_id and the same routine_id. If one exists, that run is returned instead of a new one. The trigger is not compared: a manual wake on NF-12 while an assignment run for NF-12 is still queued returns the assignment run. Once a run is claimed it no longer blocks new runs.

LifecycleCopy Anchor Link

• A run never goes back to queued. A PATCH with status: queued returns 400 INVALID_STATE.
• A finished run (succeeded, failed or cancelled) rejects every further update with 400 RUN_FINISHED, including cancel.
• When a run starts, its agent becomes running. When it finishes, the agent goes back to idle (or to error after a failure), unless the agent has another run still running.

Claim, lease, heartbeat and expiryCopy Anchor Link

Runners take work with POST /runs/claim, which atomically picks the oldest queued run whose agent is not dormant and not already running something, marks it running, stamps runner_id, started_at and heartbeat_at, and returns everything needed to execute it. One agent runs at most one claimed run at a time.

The claim is a lease. The runner keeps it alive by calling POST /runs/{run_id}/heartbeat; any PATCH /runs/{run_id} progress report also refreshes heartbeat_at. A running run whose last heartbeat (or start, if it never sent one) is older than RUN_LEASE_SECONDS (default 300) is expired: it becomes failed with an error such as "Runner my-mac:4242 stopped reporting (lease expired)". Expiry runs at the start of every claim, on POST /runs/expire-stale, and from sat scheduler start every 60 seconds.

A runner that sends a runner_id different from the one that claimed the run gets 409 RUN_LEASE_LOST and must stop. The full protocol, including what the runner does on cancel and lease loss, is in How runs work.

TranscriptCopy Anchor Link

The transcript is an ordered list of entries. Runners append with append_transcript on PATCH; the API adds system entries when the run is queued and claimed.

GET /runs leaves transcripts out; fetch one run to get its transcript.

Tokens and costCopy Anchor Link

Runners report tokens_in, tokens_out and cost_cents (integer cents). Each PATCH replaces the previous values, so the last report wins. sat runner reports what the adapter measured: Claude Code reports its own cost, while Codex runs cost 0 unless the runner sets SAT_CODEX_PRICE_IN and SAT_CODEX_PRICE_OUT. See Budgets and costs.

Finishing enforces the agent's budgetCopy Anchor Link

Every way a run can finish (a runner's final report, cancel, lease expiry, agent termination) checks the agent's monthly budget. If the agent's spend this month has reached a non-zero monthly_budget_cents, the agent is set to paused and a budget_override approval is opened (one per agent at a time). A paused agent's queued runs stay queued and are not claimed until it is resumed.

CancelCopy Anchor Link

POST /runs/{run_id}/cancel works on queued and running runs, whichever runner holds them. It is the same as a PATCH with status: cancelled and no runner_id. A runner executing the run learns about it from its next heartbeat or report (409 RUN_LEASE_LOST or 400 RUN_FINISHED) and stops. Cancelling also enforces the agent's budget.

FieldsCopy Anchor Link

RunOut, returned by the list and inside other responses. GET /runs/{run_id} returns RunDetail, which adds transcript.

StatusesCopy Anchor Link

Use itCopy Anchor Link

PermissionsCopy Anchor Link

Any member of the company can list, read, wake, claim, report on and cancel runs. Non-members get 404 NOT_FOUND. There is no separate runner role: a runner acts with the credentials of the person who started it, usually an API key.

EventsCopy Anchor Link

Heartbeats publish no events. See Live updates.

Limits and known gapsCopy Anchor Link

• The API does not execute runs. Without a runner (sat runner start or your own), runs stay queued forever.
• Dedupe compares agent, task and routine only, not the trigger.
• GET /runs returns at most 500 rows and has no paging cursor. The CLI resolves id prefixes against the 500 most recent runs.
• Cost is whatever the runner reports. SAT does not price tokens itself.
• Spend is counted by created_at, so a run's cost counts toward the month it was queued in, even if it finished in the next month.
• The transcript is stored as one JSON array on the run, with no size limit or truncation on the server.
• Run history is kept indefinitely; there is no retention or purge.

RelatedCopy Anchor Link