Get Run

GET /v1/runs/:runId

Get the status and results of a specific run.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <api-key>`
`x-workspace-id`	No	Only needed with OAuth/JWT tokens without an org context — with a Monid API key the workspace is bound to the key. See `GET /v1/auth/workspaces`

Path Parameters

Parameter	Type	Description
`runId`	string	The run ID to look up

Example Request

curl "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF" \
  -H "Authorization: Bearer monid_live_..."

const res = await fetch(
  "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF",
  {
    headers: {
      Authorization: "Bearer monid_live_...",
    },
  },
);

200 OK

Field	Type	Description
`runId`	string	Run identifier
`caller`	string	Prefixed caller id (e.g. `USER#<userId>`)
`provider`	string	Provider slug
`providerName`	string \| undefined	Provider display name
`endpoint`	string	Endpoint path
`status`	string	Run status
`stoppable`	boolean \| undefined	Whether the run may be stopped (present only for non-terminal runs)
`reason`	string \| undefined	`BLOCKED` only — why the control gate rejected the run
`controls`	array \| undefined	`BLOCKED` only — the blocking control(s)
`input`	object	Input parameters
`output`	any \| null	Provider output data (terminal runs only)
`providerResponse`	object \| undefined	Provider response metadata (incl. `httpStatus`)
`price`	object	Endpoint pricing (`amount` is `{ "value": number, "currency": "USD" }`)
`cost`	object \| undefined	Actual cost charged
`billedUnits`	number \| undefined	Units of the price’s billing unit consumed
`resultCount`	number \| undefined	Deprecated alias of `billedUnits`
`resources`	array \| undefined	Provider resources created by this run
`hints`	object \| undefined	Ready-to-use next-step commands
`createdAt`	string	ISO 8601 timestamp
`startedAt`	string \| undefined	When execution started
`completedAt`	string \| undefined	When execution finished

403 Forbidden

Returned when the run belongs to a different workspace than the caller’s.

Status vs Provider HTTP Status

Every run has two independent indicators:

status — the run lifecycle status. Did the run itself complete?
providerResponse.httpStatus — the provider’s HTTP response code. Did the data provider return good data?

Run Status

Status	Meaning
`READY`	Queued, waiting to start
`RUNNING`	Actively executing
`STOPPING`	Stop requested, shutting down (transient)
`COMPLETED`	Run finished — the provider was called and responded
`FAILED`	Infrastructure failure — pipeline crash or internal error (our fault)
`BLOCKED`	Rejected by a control gate before execution (see `reason` and `controls`)
`STOPPED`	Stopped by request before completing (zero-billed)
`TIMED_OUT`	Ran past its time budget (terminal; distinct from `FAILED`)

Provider HTTP Status

When a run is COMPLETED, check providerResponse.httpStatus:

HTTP Status	Meaning
`200`	Success — `output` contains results
`400`	Bad request — invalid parameters sent to provider
`404`	Not found — no match for the query
`429`	Rate limited — provider throttled the request
`500`	Provider error — the provider’s service failed

Provider errors are not charged — cost.value will be 0.

Caching

Terminal runs include Cache-Control: private, max-age=60 (60 seconds). Running runs are not cached.

Auth

Endpoints

Runs

Wallet

Headers

Path Parameters

Example Request

200 OK

403 Forbidden

Status vs Provider HTTP Status

Run Status

Provider HTTP Status

Caching

​Headers

​Path Parameters

​Example Request

​200 OK

​403 Forbidden

​Status vs Provider HTTP Status

​Run Status

​Provider HTTP Status

​Caching

Headers

Path Parameters

Example Request

200 OK

403 Forbidden

Status vs Provider HTTP Status

Run Status

Provider HTTP Status

Caching