Get Task Status

GEThttps://agent.blackbox.ai/api/v1/tasks/{runId}/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:

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

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Path Parameters

runIdstringrequired

The unique run identifier returned when the task was created.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response Fields

runIdstring

Unique identifier for this agent run.

statusstring

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

progressnumber

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

errorstring | null

Error message if the run failed, null otherwise.

startedAtstring | null

ISO 8601 timestamp when the run started executing.

completedAtstring | null

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

Request Example

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

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}%)`);

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']}%)")

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"])
}

Response Example

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

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

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

{
  "error": "Task not found"
}

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