Skip to main content
GET
https://cloud.blackbox.ai
/
api
/
tasks
curl 'https://cloud.blackbox.ai/api/tasks?limit=50&offset=0&filter=all' \
  -H 'Authorization: Bearer bb_YOUR_API_KEY' \
  -H 'Accept: application/json'

{
  "tasks": [
    {
      "id": "9qQe2F8Z_nXx9-eJA0BD6",
      "userId": "[email protected]",
      "teamId": null,
      "prompt": "Add Stripe payment integration",
      "repoUrl": "https://github.com/username/repository.git",
      "selectedAgent": "claude",
      "selectedModel": "claude-sonnet-4.5",
      "installDependencies": false,
      "maxDuration": 300,
      "status": "completed",
      "progress": 100,
      "error": null,
      "selectedBranch": "main",
      "branchName": "feature/stripe-payment-xyz",
      "sandboxUrl": null,
      "sandboxId": "sbx_ABC123",
      "merged": false,
      "diffStats": {
        "totalLinesAdded": 247,
        "totalLinesRemoved": 12,
        "totalFilesChanged": 4
      },
      "autoDeployEnabled": false,
      "vercelDeploymentSettings": null,
      "deployments": null,
      "badge": null,
      "batchId": null,
      "createdAt": "2025-11-20T23:37:17.761Z",
      "updatedAt": "2025-11-20T23:41:39.024Z",
      "completedAt": "2025-11-20T23:41:39.024Z",
      "creatorName": "John Doe",
      "creatorImage": "https://avatars.githubusercontent.com/u/123456",
      "prNumber": 42,
      "prUrl": "https://github.com/username/repository/pull/42",
      "isEmptyGitUser": false
    },
    {
      "id": "abc123xyz456def789",
      "userId": "[email protected]",
      "teamId": null,
      "prompt": "Add unit tests for authentication",
      "repoUrl": "https://github.com/username/repository.git",
      "selectedAgent": "blackbox",
      "selectedModel": "blackbox-pro",
      "installDependencies": false,
      "maxDuration": 300,
      "status": "processing",
      "progress": 45,
      "error": null,
      "selectedBranch": "main",
      "branchName": "tests/auth-tests-abc",
      "sandboxUrl": null,
      "sandboxId": "sbx_XYZ789",
      "merged": false,
      "diffStats": null,
      "autoDeployEnabled": false,
      "vercelDeploymentSettings": null,
      "deployments": null,
      "badge": null,
      "batchId": null,
      "createdAt": "2025-11-21T10:10:00.000Z",
      "updatedAt": "2025-11-21T10:15:30.123Z",
      "completedAt": null,
      "creatorName": "John Doe",
      "creatorImage": "https://avatars.githubusercontent.com/u/123456",
      "prNumber": null,
      "prUrl": null,
      "isEmptyGitUser": false
    }
  ],
  "hasMore": true,
  "offset": 0,
  "limit": 50
}
This endpoint allows you to retrieve a list of tasks that have been created. You can filter by task type, status, and use pagination to navigate through your task history.

​
Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:
  1. Click on your Profile Image in the top right corner at cloud.blackbox.ai
  2. Click on “BLACKBOX API Token” from the dropdown menu
  3. Copy the existing token or click “Generate” if you don’t have one yet
Your API key will be in the format: bb_xxxxxxxxxxxxxxxxxxxxxx

​
Headers

​
Authorization
string
required
API Key of the form Bearer <api_key>.Example: Bearer bb_b41b647ffbfed27f61656049d3eaeef3d903cc503345d9eb80080d98bc0

​
Query Parameters

​
limit
integer
default:"50"
Number of tasks to return per page.Range: 1-100
Default: 50Example: limit=10
​
offset
integer
default:"0"
Number of tasks to skip for pagination.Default: 0Example: offset=50 (to get the second page with limit=50)
​
filter
string
default:"all"
Filter tasks by type.Available values:
  • all - Return all tasks (default)
  • tasks - Return only non-batch tasks
  • batch - Return only batch tasks
Example: filter=tasks
​
status
string
Filter tasks by status.Available values:
  • active - Return only active tasks (pending, processing, saving)
  • completed - Return only completed tasks
  • failed - Return only failed tasks
  • stopped - Return only stopped tasks
Example: status=active

​
Response Fields

​
tasks
array
Array of task objects. Each task contains:
​
hasMore
boolean
Indicates if there are more tasks available beyond the current page.
​
offset
number
The offset value used for this request.
​
limit
number
The limit value used for this request.
curl 'https://cloud.blackbox.ai/api/tasks?limit=50&offset=0&filter=all' \
  -H 'Authorization: Bearer bb_YOUR_API_KEY' \
  -H 'Accept: application/json'

{
  "tasks": [
    {
      "id": "9qQe2F8Z_nXx9-eJA0BD6",
      "userId": "[email protected]",
      "teamId": null,
      "prompt": "Add Stripe payment integration",
      "repoUrl": "https://github.com/username/repository.git",
      "selectedAgent": "claude",
      "selectedModel": "claude-sonnet-4.5",
      "installDependencies": false,
      "maxDuration": 300,
      "status": "completed",
      "progress": 100,
      "error": null,
      "selectedBranch": "main",
      "branchName": "feature/stripe-payment-xyz",
      "sandboxUrl": null,
      "sandboxId": "sbx_ABC123",
      "merged": false,
      "diffStats": {
        "totalLinesAdded": 247,
        "totalLinesRemoved": 12,
        "totalFilesChanged": 4
      },
      "autoDeployEnabled": false,
      "vercelDeploymentSettings": null,
      "deployments": null,
      "badge": null,
      "batchId": null,
      "createdAt": "2025-11-20T23:37:17.761Z",
      "updatedAt": "2025-11-20T23:41:39.024Z",
      "completedAt": "2025-11-20T23:41:39.024Z",
      "creatorName": "John Doe",
      "creatorImage": "https://avatars.githubusercontent.com/u/123456",
      "prNumber": 42,
      "prUrl": "https://github.com/username/repository/pull/42",
      "isEmptyGitUser": false
    },
    {
      "id": "abc123xyz456def789",
      "userId": "[email protected]",
      "teamId": null,
      "prompt": "Add unit tests for authentication",
      "repoUrl": "https://github.com/username/repository.git",
      "selectedAgent": "blackbox",
      "selectedModel": "blackbox-pro",
      "installDependencies": false,
      "maxDuration": 300,
      "status": "processing",
      "progress": 45,
      "error": null,
      "selectedBranch": "main",
      "branchName": "tests/auth-tests-abc",
      "sandboxUrl": null,
      "sandboxId": "sbx_XYZ789",
      "merged": false,
      "diffStats": null,
      "autoDeployEnabled": false,
      "vercelDeploymentSettings": null,
      "deployments": null,
      "badge": null,
      "batchId": null,
      "createdAt": "2025-11-21T10:10:00.000Z",
      "updatedAt": "2025-11-21T10:15:30.123Z",
      "completedAt": null,
      "creatorName": "John Doe",
      "creatorImage": "https://avatars.githubusercontent.com/u/123456",
      "prNumber": null,
      "prUrl": null,
      "isEmptyGitUser": false
    }
  ],
  "hasMore": true,
  "offset": 0,
  "limit": 50
}

​
Use Cases

​
Monitor Active Tasks

Track all currently running tasks: 
const response = await fetch(
  'https://cloud.blackbox.ai/api/tasks?filter=all&status=active&limit=100',
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      Accept: "application/json",
    },
  }
);

const { tasks } = await response.json();
console.log(`Active tasks: ${tasks.length}`);

tasks.forEach(task => {
  console.log(`${task.id}: ${task.progress}% - ${task.status}`);
});

​
Task History Dashboard

Build a dashboard showing recent task activity: 
async function getTaskStats() {
  const response = await fetch(
    'https://cloud.blackbox.ai/api/tasks?limit=100&offset=0&filter=all',
    {
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        Accept: "application/json",
      },
    }
  );

  const { tasks } = await response.json();

  const stats = {
    total: tasks.length,
    completed: tasks.filter(t => t.status === 'completed').length,
    failed: tasks.filter(t => t.status === 'error').length,
    active: tasks.filter(t => ['pending', 'processing', 'saving'].includes(t.status)).length,
  };

  return stats;
}

​
Filter by Agent

Get tasks executed by a specific agent: 
const response = await fetch(
  'https://cloud.blackbox.ai/api/tasks?limit=50&offset=0&filter=all',
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      Accept: "application/json",
    },
  }
);

const { tasks } = await response.json();

// Filter by agent on client side
const claudeTasks = tasks.filter(t => t.selectedAgent === 'claude');
const blackboxTasks = tasks.filter(t => t.selectedAgent === 'blackbox');

console.log(`Claude tasks: ${claudeTasks.length}`);
console.log(`BLACKBOX tasks: ${blackboxTasks.length}`);

​
Batch Task Management

Retrieve and manage batch tasks: 
const response = await fetch(
  'https://cloud.blackbox.ai/api/tasks?limit=50&offset=0&filter=batch',
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      Accept: "application/json",
    },
  }
);

const { tasks } = await response.json();

// Group by batch ID
const batches = tasks.reduce((acc, task) => {
  const batchId = task.batchId;
  if (!acc[batchId]) acc[batchId] = [];
  acc[batchId].push(task);
  return acc;
}, {});

console.log(`Total batches: ${Object.keys(batches).length}`);

​
Error Codes

Status CodeErrorDescription
200SuccessTasks retrieved successfully
401UnauthorizedInvalid or missing API key
403ForbiddenUser is not a member of the selected team
500Internal Server ErrorDatabase operation failed