Circuit Runs

A circuit run is a single execution of a circuit version. When you submit a query (see Querying AI Circuits), ModelWorks returns a run UID immediately and executes the work asynchronously. This guide covers fetching run results and listing runs.

Base URL

All examples assume the following base URL:

Text

https://modelworks.ai/api

Authentication

Fetching a run requires an API token for private runs (Authorization: Bearer YOUR_API_TOKEN); public runs need no auth. See Authentication. List endpoints support limit and page pagination and return a meta object with total_count, limit, and page.

The run lifecycle

Every run moves through a simple lifecycle:

Text

PROVISIONED -> RUNNING -> COMPLETED
                        \-> EXCEPTION

State	Meaning
`PROVISIONED`	The run has been accepted and is queued or starting. This is the state you see in the immediate query response.
`RUNNING`	The circuit is actively executing its steps.
`COMPLETED`	The run finished successfully. `result_blob` is populated.
`EXCEPTION`	The run failed. Inspect the result and error details for the cause.

You receive the run UID in the immediate response from the query endpoint (for example, POST /circuit-adaptors/{adaptor_uid}/query). Use that UID to poll or fetch the final result here.

Public vs private runs

Public runs (is_public: true) can be read by anyone — no token required. Only the circuit owner can mark a run public.
Private runs (is_public: false, the default) require the owner's API token to read.

The result_blob field holds the full JSON output produced by the circuit's steps, and is present once the run reaches COMPLETED.

Get a run

GET /circuit-runs/{uid}

Fetch a run by its UID. Public runs need no auth; private runs require the owner's token.

Bash

curl https://modelworks.ai/api/circuit-runs/fdd8a9c2-695a-4ef3-95c6-0be1cba77cc6 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Parameter	Type	Description
`uid`	string	The run's unique ID.

Response (200 OK)

JSON

{
  "status": "success",
  "payload": {
    "uid": "fdd8a9c2-695a-4ef3-95c6-0be1cba77cc6",
    "user_uid": "4a1b2c3d-...",
    "circuit_uid": "73120d53-...",
    "circuit_version_uid": "73120d53-...",
    "created_at": "2025-06-23T18:25:43.511Z",
    "ended_at": "2025-06-23T18:25:45.122Z",
    "state": "COMPLETED",
    "is_public": false,
    "document_type": "circuit_run",
    "result_blob": {
      "chat_completion_output": "..."
    }
  }
}

CircuitRun fields

Field	Type	Description
`uid`	string	Unique run identifier.
`user_uid`	string	The user who initiated the run.
`circuit_uid`	string	The circuit that was run.
`circuit_version_uid`	string	The specific version that was run.
`created_at`	string (ISO 8601)	When the run started.
`ended_at`	string (ISO 8601)	When the run finished (absent while in flight).
`state`	string	Lifecycle state: `PROVISIONED`, `RUNNING`, `COMPLETED`, or `EXCEPTION`.
`is_public`	boolean	Whether the run is publicly viewable.
`document_type`	string	Document discriminator (always `circuit_run`).
`result_blob`	object	Full JSON output from the circuit's steps (present when `COMPLETED`).

List runs for a version

GET /circuit-versions/{version_uid}/circuit-runs

List the completed public runs for a version. Paginated.

Bash

curl "https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/circuit-runs?limit=10&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Parameter	Type	Description
`version_uid`	string	The version's unique ID.
`limit`	integer	Items per page (optional).
`page`	integer	1-based page number (optional).

List runs for a circuit

GET /circuits/{circuit_uid}/circuit-runs

List the completed public runs for a circuit (across all versions). Paginated.

Bash

curl "https://modelworks.ai/api/circuits/73120d53-bf89-44fa-a035-5b88fe41574a/circuit-runs?limit=10&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Parameter	Type	Description
`circuit_uid`	string	The circuit's unique ID.
`limit`	integer	Items per page (optional).
`page`	integer	1-based page number (optional).

Best practices

Poll sparingly. A run may take seconds to minutes depending on the circuit. Use exponential backoff (for example, 1s, 2s, 4s, 8s…) rather than tight loops, or switch to SSE streaming for live updates (see Querying Circuit Adaptors).
Pin a version. Cache the primary version UID once via GET /circuits/{circuit_uid}/primary and reuse it; don't re-fetch on every call.
Store the run UID. You get it from the query response immediately — persist it so you can retrieve the result later without re-running.
Watch your credits. Each run consumes credits; monitor usage in the dashboard.

Circuit Runs

On this page