List Tasks - BLACKBOX AI

curl 'https://agent.blackbox.ai/api/v1/tasks?page=1&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "tasks": [
    {
      "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "chatId": "chat_def789ghi012",
      "status": "completed",
      "model": null,
      "createdAt": "2026-05-19T10:00:00.000Z",
      "startedAt": "2026-05-19T10:00:02.000Z",
      "completedAt": "2026-05-19T10:04:45.000Z",
      "assistantMessageId": "msg_abc123xyz456"
    },
    {
      "taskId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "runId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "chatId": "chat_ghi012jkl345",
      "status": "running",
      "model": null,
      "createdAt": "2026-05-19T10:10:00.000Z",
      "startedAt": "2026-05-19T10:10:01.000Z",
      "completedAt": null,
      "assistantMessageId": "msg_def456uvw789"
    }
  ],
  "page": 1,
  "limit": 20,
  "hasMore": false
}

GET

api

tasks

curl 'https://agent.blackbox.ai/api/v1/tasks?page=1&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "tasks": [
    {
      "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "chatId": "chat_def789ghi012",
      "status": "completed",
      "model": null,
      "createdAt": "2026-05-19T10:00:00.000Z",
      "startedAt": "2026-05-19T10:00:02.000Z",
      "completedAt": "2026-05-19T10:04:45.000Z",
      "assistantMessageId": "msg_abc123xyz456"
    },
    {
      "taskId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "runId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "chatId": "chat_ghi012jkl345",
      "status": "running",
      "model": null,
      "createdAt": "2026-05-19T10:10:00.000Z",
      "startedAt": "2026-05-19T10:10:01.000Z",
      "completedAt": null,
      "assistantMessageId": "msg_def456uvw789"
    }
  ],
  "page": 1,
  "limit": 20,
  "hasMore": false
}

This endpoint returns a paginated list of all agent runs belonging to the authenticated user. You can filter by status and control pagination using page and limit.

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

Query Parameters

page

integer

default:"1"

Page number for pagination.Default: 1Example: page=2

limit

integer

default:"20"

Number of tasks to return per page.Range: 1 – 100. Default: 20.Example: limit=50

status

string

Filter tasks by status. If omitted, all statuses are returned.Available values:

queued — Task is waiting to start
running — Task is actively executing
completed — Task finished successfully
failed — Task encountered an error
cancelled — Task was cancelled by user
interrupted — Task was interrupted

Example: status=running

Response Fields

tasks

array

Array of task run objects.

Show Task Object

taskId

string

Unique identifier for the task (same as runId).

runId

string

Unique identifier for this agent run.

chatId

string

UUID of the chat thread this run belongs to.

status

string

Current status: queued, running, completed, failed, cancelled, or interrupted.

model

string | null

Model used for this run (may be null).

createdAt

string

ISO 8601 timestamp when the run was created.

startedAt

string

ISO 8601 timestamp when the run started executing. Falls back to createdAt if not yet started.

completedAt

string | null

ISO 8601 timestamp when the run completed.

assistantMessageId

string | null

ID of the assistant message generated by this run.

page

number

Current page number.

limit

number

Number of items per page used for this request.

hasMore

boolean

Whether there are more tasks beyond the current page.

curl 'https://agent.blackbox.ai/api/v1/tasks?page=1&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "tasks": [
    {
      "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "chatId": "chat_def789ghi012",
      "status": "completed",
      "model": null,
      "createdAt": "2026-05-19T10:00:00.000Z",
      "startedAt": "2026-05-19T10:00:02.000Z",
      "completedAt": "2026-05-19T10:04:45.000Z",
      "assistantMessageId": "msg_abc123xyz456"
    },
    {
      "taskId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "runId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "chatId": "chat_ghi012jkl345",
      "status": "running",
      "model": null,
      "createdAt": "2026-05-19T10:10:00.000Z",
      "startedAt": "2026-05-19T10:10:01.000Z",
      "completedAt": null,
      "assistantMessageId": "msg_def456uvw789"
    }
  ],
  "page": 1,
  "limit": 20,
  "hasMore": false
}

Use Cases

Paginate Through All Tasks

async function getAllTasks(apiKey) {
  const API_URL = "https://agent.blackbox.ai/api/v1/tasks";
  const allTasks = [];
  let page = 1;

  while (true) {
    const response = await fetch(`${API_URL}?page=${page}&limit=100`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const data = await response.json();
    allTasks.push(...data.tasks);

    if (!data.hasMore) break;
    page++;
  }

  return allTasks;
}

Monitor Active Tasks

const response = await fetch(
  "https://agent.blackbox.ai/api/v1/tasks?status=running&limit=100",
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { tasks } = await response.json();
console.log(`Active tasks: ${tasks.length}`);
tasks.forEach(t => console.log(`${t.runId} — started: ${t.startedAt}`));

Error Codes

Status Code	Error	Description
200	Success	Tasks retrieved successfully
401	Unauthorized	Invalid or missing API key
500	Internal Server Error	Database error

Create Task Get Task

​Authentication

​Headers

​Query Parameters

​Response Fields

​Use Cases

​Paginate Through All Tasks

​Monitor Active Tasks

​Error Codes

Authentication

Headers

Query Parameters

Response Fields

Use Cases

Paginate Through All Tasks

Monitor Active Tasks

Error Codes