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

# Agent Run Status

> Check the current status of a Claude Agent run by runId. Checks live in-memory state first, falls back to the database.

This endpoint returns the raw internal status of an agent run identified by `runId`. Unlike the task status endpoint, this returns the internal status values directly (not mapped to external values) and also includes the `assistantMessageId`.

## Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:

1. Go to [app.blackbox.ai/agent-api](https://app.blackbox.ai/agent-api) and click **Get an API Key** (requires a Pro subscription)
2. Once provisioning completes, you will be redirected to your [Dashboard](https://app.blackbox.ai/dashboard)
3. From the Dashboard, create an API key to use with all Agent API requests

Your API key will be in the format: `sk-xxxxxxxxxxxxxxxxxxxxxx`

## Headers

<ParamField header="Authorization" type="string" required>
  API Key of the form `Bearer <api_key>`.

  Example: `Bearer sk_b41b647ffbfed27f616560`
</ParamField>

## Query Parameters

<ParamField query="runId" type="string" required>
  The unique run identifier returned when the task was created.

  Example: `runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890`
</ParamField>

## Response Fields

<ResponseField name="runId" type="string | null">
  The run identifier. `null` if not found.
</ResponseField>

<ResponseField name="status" type="string | null">
  Internal status of the run.

  Possible values: `queued`, `running`, `completed`, `failed`, `cancelled`, `interrupted`, or `null` if not found.
</ResponseField>

<ResponseField name="assistantMessageId" type="string | null">
  ID of the assistant message being generated. `null` if not yet assigned or not found.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the run failed, `null` otherwise.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/agent/status?runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const API_KEY = "YOUR_API_KEY";
  const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

  const response = await fetch(
    `https://agent.blackbox.ai/api/v1/agent/status?runId=${RUN_ID}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  const data = await response.json();
  console.log(`Status: ${data.status}`);
  console.log(`Message ID: ${data.assistantMessageId}`);
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  API_KEY = "YOUR_API_KEY"
  RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  response = requests.get(
      "https://agent.blackbox.ai/api/v1/agent/status",
      headers={"Authorization": f"Bearer {API_KEY}"},
      params={"runId": RUN_ID},
  )
  data = response.json()
  print(f"Status: {data['status']}")
  print(f"Message ID: {data['assistantMessageId']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Running theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "running",
    "assistantMessageId": "msg_abc123xyz456",
    "error": null
  }
  ```

  ```json Completed theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "assistantMessageId": "msg_abc123xyz456",
    "error": null
  }
  ```

  ```json Not Found theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "runId": null,
    "status": null,
    "assistantMessageId": null,
    "error": null
  }
  ```

  ```json Error - Missing runId theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "runId query parameter is required"
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error        | Description                                    |
| ----------- | ------------ | ---------------------------------------------- |
| 200         | Success      | Status returned (may be null if run not found) |
| 400         | Bad Request  | Missing `runId` query parameter                |
| 401         | Unauthorized | Invalid or missing API key                     |