Get Task List

Retrieve a paginated list of tasks with filtering options to monitor and manage your AI agent executions.

GET https://cloud.blackbox.ai/api/tasks

cURL

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

Success Response

{
  "tasks": [
    {
      "id": "9qQe2F8Z_nXx9-eJA0BD6",
      "userId": "[e-mail]",
      "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": "[e-mail]",
      "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: 50

Example: limit=10

offset · integer · default: "0"

Number of tasks to skip for pagination.

Default: 0

Example: 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:

Show Task Object

id · string

Unique identifier for the task.

userId · string

Email or ID of the user who created the task.

teamId · string | null

Team ID if the task belongs to a team, null for personal tasks.

prompt · string

The task description or instruction provided.

repoUrl · string

GitHub repository URL the task was executed on.

selectedAgent · string

The AI agent used (claude, blackbox, codex, gemini).

selectedModel · string

The specific AI model used.

installDependencies · boolean

Whether dependencies were installed during execution.

maxDuration · number

Maximum duration allowed for the task in seconds.

status · string

Current status of the task.

Possible values:

• pending - Task is queued
• processing - Task is being executed
• saving - Task is saving results
• completed - Task finished successfully
• error - Task failed
• stopped - Task was stopped by user
• timeout - Task exceeded time limit

progress · number

Task completion percentage (0-100).

error · string | null

Error message if the task failed.

selectedBranch · string

The branch that was worked on.

branchName · string | null

The new branch name created for the task.

sandboxUrl · string | null

URL to the sandbox environment (if applicable).

sandboxId · string | null

Identifier for the sandbox environment.

merged · boolean

Whether the changes have been merged.

diffStats · object | null

Statistics about code changes made.

Contains:

• totalLinesAdded - Number of lines added
• totalLinesRemoved - Number of lines removed
• totalFilesChanged - Number of files modified

autoDeployEnabled · boolean | null

Whether auto-deployment is enabled.

vercelDeploymentSettings · object | null

Vercel deployment configuration (if applicable).

deployments · array | null

Array of deployment information.

badge · string | null

Badge or label associated with the task.

batchId · string | null

Batch ID if this task is part of a batch.

createdAt · string

ISO 8601 timestamp when the task was created.

updatedAt · string

ISO 8601 timestamp when the task was last updated.

completedAt · string | null

ISO 8601 timestamp when the task completed.

creatorName · string | null

Name of the user who created the task.

creatorImage · string | null

Profile image URL of the task creator.

prNumber · number | null

Pull request number if a PR was created.

prUrl · string | null

URL to the pull request if created.

isEmptyGitUser · boolean

Whether the task was created for a user without GitHub connection.

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

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

Success Response

{
  "tasks": [
    {
      "id": "9qQe2F8Z_nXx9-eJA0BD6",
      "userId": "[e-mail]",
      "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": "[e-mail]",
      "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 Code	Error	Description
200	Success	Tasks retrieved successfully
401	Unauthorized	Invalid or missing API key
403	Forbidden	User is not a member of the selected team
500	Internal Server Error	Database operation failed