Skip to main content
A run executes one published recipe revision.

​
Method signature (Python SDK)

client.runs.create(
    recipe_id: str,
    inputs: dict[str, str] | None = None,
    ingest: dict[str, list[IngestSource]] | None = None,
    *,
    wait: bool = True,
    timeout: float = 300.0,
    poll_interval: float = 0.5,
    max_poll_interval: float = 5.0,
)

​
Basic run

run = client.runs.create(recipe_id="01JEXAMPLE00000000000000000")
print(run["status"])  # done (or raises on failed/cancelled/blocked)

​
Inputs

run = client.runs.create(
    recipe_id="01JEXAMPLE00000000000000000",
    inputs={
        "company_name": "Acme Corp",
        "industry": "Technology",
    },
)
inputs is a dict[str, str] in v1.

​
Ingest overrides

from stewai import IngestSource

run = client.runs.create(
    recipe_id="01JEXAMPLE00000000000000000",
    ingest={
        "ingest_step_1": [
            IngestSource(uri="https://example.com/report.pdf", kind="url"),
            IngestSource(uri="doc://01ABCDEF...", kind="file", label="Report"),
        ]
    },
)
Valid source patterns in v1:
  • kind="url" => http://... or https://...
  • kind="file" => doc://...

​
Non-blocking mode

run = client.runs.create(
    recipe_id="01JEXAMPLE00000000000000000",
    wait=False,
)

run = client.runs.get(run["id"])
run = client.runs.wait(run["id"], timeout=600)

​
Polling behavior

When waiting, the SDK polls GET /v1/runs/{id}/ with exponential backoff + jitter.
  • starts at poll_interval
  • increases up to max_poll_interval
  • stops on terminal statuses: done, failed, cancelled, blocked

​
Run statuses

StatusMeaning
queuedAccepted and waiting to run
runningExecuting
doneCompleted successfully
failedTerminal failure
cancelledTerminal cancellation
blockedTerminal blocked state

​
REST API v1

​
Create

POST /v1/runs/
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "recipe_id": "01JEXAMPLE00000000000000000",
  "inputs": {
    "company_name": "Acme Corp"
  }
}
Typical 202 body: 
{
  "id": "01JRUN...",
  "recipe_id": "01JEXAMPLE00000000000000000",
  "status": "queued",
  "created_at": "2026-01-15T10:30:00Z",
  "duration_ms": 0
}

​
Get run

GET /v1/runs/{run_id}/

​
Get steps

GET /v1/runs/{run_id}/steps/

​
See also