Get Task Status - BLACKBOX AI

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:

Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
Once provisioning completes, you will be redirected to your Dashboard
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 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "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

​Authentication

​Headers

​Path Parameters

​Response Fields

​Use Cases

​Poll Until Done

​Exponential Backoff Polling

​Status Values Reference

​Error Codes

Authentication

Headers

Path Parameters

Response Fields

Use Cases

Poll Until Done

Exponential Backoff Polling

Status Values Reference

Error Codes