Skip to content

Runs

A run is one execution of a template. Runs are durable and resumable: every step's outcome is written down as it happens, so a run interrupted at any point — by waiting, by a deploy, by a crash — picks up exactly where it left off.

Starting a run

POST /api/v1/projects/{project_uuid}/workflows/instances
{
  "template_name": "reviewed_publish",
  "template_version": 1,
  "input": {
    "message": "Draft the announcement",
    "secret": "<passphrase>",
    "url": "https://your-service.example/work",
    "reviewer_url": "https://your-service.example/review"
  }
}
  • input is your bag of run inputs — step parameters like url, the webhook secret (see review workflows), and anything your own steps reference. The secret is hashed immediately and never stored in plaintext.
  • Runs execute the exact template version they were created with — editing a template later never affects existing runs.
  • Every run has a spend cap. Pass an explicit budget, put a budget condition in the template, or accept the server-side default; a run that exceeds its cap stops with a budget_exhausted exception.

Statuses

Status Meaning
new Created, not yet executing.
running Executing steps.
parked Waiting — typically for one of your agents to call back.
done Finished; the last step's result is the run's result.
exception A step failed (or the budget was exhausted).
canceled Canceled by request.

Waiting is free

A run waiting on an until gate:

  • holds no resources and consumes no budget;
  • has no deadline — your agent may respond in seconds or in days, and may restart in between;
  • needs no polling — the only things that wake it are your agent's callback or a cancel.

A run waiting on a when gate re-checks periodically; the two behaviors are distinguishable in the run's status detail.

Usage metering

Every step execution counts as one work unit against your weekly plan allowance (see pricing). If the allowance is exhausted mid-run, the run parks until the start of your next weekly period, then resumes on its own — you do not need to restart it.

Watching and controlling runs

GET  …/workflows/instances?status=parked        # list runs
GET  …/workflows/instances/{run_uuid}           # step states + results
PATCH …/workflows/instances/{run_uuid}          # cancel a run

Canceling a waiting run ends it immediately — a parked run otherwise waits forever. Read access shows step statuses and results but redacts conversation-derived content and credentials.

Next