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

# Get Run

> Get the status and results of a specific run.

```text theme={null}
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`](/docs/api/auth/workspaces) |

## Path Parameters

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

## Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF" \
    -H "Authorization: Bearer monid_live_..."
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF",
    {
      headers: {
        Authorization: "Bearer monid_live_...",
      },
    },
  );
  ```
</CodeGroup>

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

1. **`status`** — the run lifecycle status. Did the run itself complete?
2. **`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.