> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```http theme={null}
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:

```text theme={null}
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.

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