Get Task Status

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

GET /api/v1/tasks/{runId}/status

cURL

curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Running

{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "in_progress",
  "progress": 42,
  "error": null,
  "startedAt": "2026-05-19T10:00:02.000Z",
  "completedAt": null
}

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 and click Get an API Key (requires a Pro subscription)
2. Once provisioning completes, you will be redirected to your 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

Authorization · string · required

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Path Parameters

runId · string · required

The unique run identifier returned when the task was created.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response Fields

runId · string

Unique identifier for this agent run.

status · 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

progress · number

Estimated completion percentage (0–100). Linearly estimated from elapsed time for running tasks; 100 for completed; 0 for failed/cancelled.

error · string | null

Error message if the run failed, null otherwise.

startedAt · string | null

ISO 8601 timestamp when the run started executing.

completedAt · string | null

ISO 8601 timestamp when the run completed. null if still running.

cURL

curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Running

{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "in_progress",
  "progress": 42,
  "error": null,
  "startedAt": "2026-05-19T10:00:02.000Z",
  "completedAt": null
}

Use Cases

Poll Until Done

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

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