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

# Get Task Status

> Lightweight status poll for a task run. Returns only status, progress, and timestamps — no messages or GitHub details.

This endpoint returns only the essential status fields for a task run — no messages, no GitHub details. Use it to poll task progress without fetching the full task payload.

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

## Path Parameters

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

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

## Response Fields

<ResponseField name="runId" type="string">
  Unique identifier for this agent run.
</ResponseField>

<ResponseField name="status" type="string">
  Current external status of the run.

  Possible values:

  * `pending` — Task is waiting to start
  * `in_progress` — Agent is actively executing
  * `completed` — Task finished successfully
  * `failed` — Task encountered an error
  * `cancelled` — Task was cancelled by user
  * `interrupted` — Task was interrupted
</ResponseField>

<ResponseField name="progress" type="number">
  Estimated completion percentage (0–100). Linearly estimated from elapsed time for running tasks; `100` for completed; `0` for failed/cancelled.
</ResponseField>

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

<ResponseField name="startedAt" type="string | null">
  ISO 8601 timestamp when the run started executing.
</ResponseField>

<ResponseField name="completedAt" type="string | null">
  ISO 8601 timestamp when the run completed. `null` if still running.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status' \
    -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/tasks/${RUN_ID}/status`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  const status = await response.json();
  console.log(`${status.runId}: ${status.status} (${status.progress}%)`);
  ```

  ```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(
      f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/status",
      headers={"Authorization": f"Bearer {API_KEY}"},
  )
  s = response.json()
  print(f"{s['runId']}: {s['status']} ({s['progress']}%)")
  ```

  ```go Go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  package main

  import (
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      apiKey := "YOUR_API_KEY"
      runId := "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      url := fmt.Sprintf("https://agent.blackbox.ai/api/v1/tasks/%s/status", runId)

      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Set("Authorization", "Bearer "+apiKey)

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      body, _ := io.ReadAll(resp.Body)
      var result map[string]interface{}
      json.Unmarshal(body, &result)
      fmt.Printf("%s: %s (%.0f%%)\n", result["runId"], result["status"], result["progress"])
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Running theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "in_progress",
    "progress": 42,
    "error": null,
    "startedAt": "2026-05-19T10:00:02.000Z",
    "completedAt": null
  }
  ```

  ```json Completed theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "progress": 100,
    "error": null,
    "startedAt": "2026-05-19T10:00:02.000Z",
    "completedAt": "2026-05-19T10:04:45.000Z"
  }
  ```

  ```json Failed theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "failed",
    "progress": 0,
    "error": "Repository clone failed: authentication required",
    "startedAt": "2026-05-19T10:00:02.000Z",
    "completedAt": "2026-05-19T10:00:15.000Z"
  }
  ```

  ```json Error - Not Found theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Task not found"
  }
  ```
</ResponseExample>

## Use Cases

### Poll Until Done

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
async function waitForCompletion(runId, apiKey) {
  const DONE = ["completed", "failed", "cancelled", "interrupted"];
  const url = `https://agent.blackbox.ai/api/v1/tasks/${runId}/status`;

  while (true) {
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const s = await res.json();

    console.log(`${s.status} — ${s.progress}%`); // e.g. "in_progress — 42%"

    if (DONE.includes(s.status)) return s;

    await new Promise(r => setTimeout(r, 2000));
  }
}
```

### Exponential Backoff Polling

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
async function pollWithBackoff(runId, apiKey) {
  const DONE = ["completed", "failed", "cancelled", "interrupted"];
  const url = `https://agent.blackbox.ai/api/v1/tasks/${runId}/status`;
  let delay = 1000;

  while (true) {
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const s = await res.json();

    if (DONE.includes(s.status)) return s;

    await new Promise(r => setTimeout(r, delay));
    delay = Math.min(delay * 2, 30000); // cap at 30s
  }
}
```

## Status Values Reference

| Status        | Description                       | Terminal? |
| ------------- | --------------------------------- | --------- |
| `pending`     | Waiting to start                  | No        |
| `in_progress` | Actively executing                | No        |
| `completed`   | Finished successfully             | Yes       |
| `failed`      | Encountered an error              | Yes       |
| `cancelled`   | Cancelled by user                 | Yes       |
| `interrupted` | Interrupted (e.g. server restart) | Yes       |

## Error Codes

| Status Code | Error                 | Description                      |
| ----------- | --------------------- | -------------------------------- |
| 200         | Success               | Status retrieved successfully    |
| 401         | Unauthorized          | Invalid or missing API key       |
| 403         | Forbidden             | Task belongs to a different user |
| 404         | Not Found             | Task not found                   |
| 500         | Internal Server Error | Database error                   |