> ## 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` | Yes      | Workspace ID — see [`GET /v1/auth/workspaces`](/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_..." \
    -H "x-workspace-id: ws_abc123"
  ```

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

## 200 OK

| Field              | Type           | Description                                     |
| ------------------ | -------------- | ----------------------------------------------- |
| `runId`            | string         | Run identifier                                  |
| `provider`         | string         | Provider slug                                   |
| `endpoint`         | string         | Endpoint path                                   |
| `status`           | string         | Run status                                      |
| `input`            | object         | Input parameters                                |
| `output`           | any \| null    | Provider output data                            |
| `providerResponse` | object \| null | Provider response metadata (incl. `httpStatus`) |
| `price`            | object         | Endpoint pricing                                |
| `cost`             | object \| null | Actual cost charged                             |
| `createdAt`        | string         | ISO 8601 timestamp                              |
| `startedAt`        | string \| null | When execution started                          |
| `completedAt`      | string \| null | When execution finished                         |

## 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                                                  |
| `COMPLETED` | Run finished — the provider was called and responded                |
| `FAILED`    | Infrastructure failure — pipeline crash, timeout, or internal error |

### 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 (`COMPLETED` or `FAILED`) include `Cache-Control: max-age=300` (5 minutes). Running runs are not cached.