Runs API Reference

Reference Starfire AI long-running run creation, status, cancellation, terminal states, event streaming, and webhook completion patterns.

Runs API reference

Runs represent durable work that can outlive a single HTTP request.

Resource model

The Alpha v1 architecture includes a run resource family conceptually similar to:

POST /v1/runs
GET  /v1/runs/{run_id}
POST /v1/runs/{run_id}/cancel

Confirm exact enabled operations and schemas in the active OpenAPI surface.

Create a run

A run request can carry the workload definition, model/tool configuration, project or organization context, and runtime limits supported by the active contract.

The create response should return a durable run identifier and initial status rather than waiting for every downstream step to finish.

Read status

Poll status when your backend does not use streaming or webhooks.

Typical lifecycle meaning:

QUEUED → RUNNING → COMPLETED
                 ↘ FAILED
                 ↘ CANCELLED

A run can also wait on approval or another dependency where the workflow supports it.

Cancel

Cancellation is best-effort and state-dependent. A completed run cannot be undone by cancelling it afterward, and an external side effect may already have occurred before cancellation reaches a later workflow step.

Streaming

Where enabled, consume run events for live progress. Your client should still confirm the final run state rather than assuming a disconnected stream means failure.

Webhooks

Use webhooks when your backend should receive completion/failure events without continuous polling.

Idempotency

For expensive run creation, use the documented idempotency mechanism when available so a network retry does not accidentally create duplicate work.

A successful POST means the run resource was accepted. It does not guarantee the long-running work will ultimately complete successfully.