v1

latestOpenAPI 3.1.02026-08-044257268.7 KB

Runs

Get a run

Poll run status and retrieve results. Terminal runs include the resolved provider output.

get/v1/runs/{runId}

Path parameters

runIdstring required

Run identifier (ULID).

Example:01JGXYZABCDEFGHJKMNPQRSTVW

Run identifier (ULID).

Response

The run (with output when terminal)

runIdstring required

Run identifier (ULID).

callerstring required

Prefixed polymorphic caller id (e.g. USER#<userId>).

providerstring required

providerNamestring

endpointstring required

Run lifecycle status. COMPLETED means the provider responded (any HTTP status); FAILED means an infrastructure failure.

stoppableboolean

reasonstring

controlsobject[]

{"stackTrail":"components:schemas:Run:properties:output","oasType":"schema","type":"unknown","description":"Provider output data (terminal runs only; may be null). Endpoints that generate FILES (e.g. audio) surface each file INSIDE output as an artifact object under a stable key: { download_link (fresh signed URL, valid until link_expires_at — re-fetch the run for a new one), content_type, link_expires_at, file_expires_at? }. After the file's retention lapses the object becomes { expired: true, file_expired_at, message }."}

resultCountnumber

billedUnitsnumber

createdAtstring date-time required

startedAtstring date-time

completedAtstring date-time

hintsobject

Example response

{
  "runId": "01JGXYZABCDEFGHJKMNPQRSTVW",
  "providerResponse": {
    "httpStatus": 200
  }
}