List Tasks

GEThttps://agent.blackbox.ai/api/v1/tasks

Retrieve a paginated list of your agent task runs with optional status filtering.

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

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Query Parameters

pageintegerdefault: 1

Page number for pagination.

Default: 1

Example: page=2

limitintegerdefault: 20

Number of tasks to return per page.

Range: 1 – 100. Default: 20.

Example: limit=50

statusstring

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

tasksarray

Array of task run objects.

Task Object

taskIdstring

Unique identifier for the task (same as runId).

runIdstring

Unique identifier for this agent run.

chatIdstring

UUID of the chat thread this run belongs to.

statusstring

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

modelstring | null

Model used for this run (may be null).

createdAtstring

ISO 8601 timestamp when the run was created.

startedAtstring

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

completedAtstring | null

ISO 8601 timestamp when the run completed.

assistantMessageIdstring | null

ID of the assistant message generated by this run.

pagenumber

Current page number.

limitnumber

Number of items per page used for this request.

hasMoreboolean

Whether there are more tasks beyond the current page.

Request Example

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

curl 'https://agent.blackbox.ai/api/v1/tasks?status=running&limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const API_KEY = "YOUR_API_KEY";
const API_URL = "https://agent.blackbox.ai/api/v1/tasks";

const params = new URLSearchParams({ page: "1", limit: "20" });

const response = await fetch(`${API_URL}?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

const data = await response.json();
console.log(`Total tasks: ${data.tasks.length}`);
console.log(`Has more: ${data.hasMore}`);
data.tasks.forEach(t => console.log(`${t.runId}: ${t.status}`));

import requests

API_KEY = "YOUR_API_KEY"
API_URL = "https://agent.blackbox.ai/api/v1/tasks"

headers = {"Authorization": f"Bearer {API_KEY}"}
params = {"page": 1, "limit": 20}

response = requests.get(API_URL, headers=headers, params=params)
data = response.json()

print(f"Tasks: {len(data['tasks'])}, Has more: {data['hasMore']}")
for task in data["tasks"]:
    print(f"{task['runId']}: {task['status']}")

package main

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

func main() {
    apiKey := "YOUR_API_KEY"
    url := "https://agent.blackbox.ai/api/v1/tasks?page=1&limit=20"

    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.Println(result)
}

Response Example

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

{
  "tasks": [],
  "page": 1,
  "limit": 20,
  "hasMore": false
}

{
  "error": "Failed to fetch tasks"
}

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