> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Task List

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

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](https://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

<ParamField header="Authorization" type="string" required>
  API Key of the form `Bearer <api_key>`.

  Example: `Bearer bb_b41b647ffbfed27f61656049d3eaeef3d903cc503345d9eb80080d98bc0`
</ParamField>

## Query Parameters

<ParamField query="limit" type="integer" default="50">
  Number of tasks to return per page.

  Range: 1-100\
  Default: 50

  Example: `limit=10`
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of tasks to skip for pagination.

  Default: 0

  Example: `offset=50` (to get the second page with limit=50)
</ParamField>

<ParamField query="filter" type="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`
</ParamField>

<ParamField query="status" type="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`
</ParamField>

## Response Fields

<ResponseField name="tasks" type="array">
  Array of task objects. Each task contains:

  <Expandable title="Task Object">
    <ResponseField name="id" type="string">
      Unique identifier for the task.
    </ResponseField>

    <ResponseField name="userId" type="string">
      Email or ID of the user who created the task.
    </ResponseField>

    <ResponseField name="teamId" type="string | null">
      Team ID if the task belongs to a team, null for personal tasks.
    </ResponseField>

    <ResponseField name="prompt" type="string">
      The task description or instruction provided.
    </ResponseField>

    <ResponseField name="repoUrl" type="string">
      GitHub repository URL the task was executed on.
    </ResponseField>

    <ResponseField name="selectedAgent" type="string">
      The AI agent used (claude, blackbox, codex, gemini).
    </ResponseField>

    <ResponseField name="selectedModel" type="string">
      The specific AI model used.
    </ResponseField>

    <ResponseField name="installDependencies" type="boolean">
      Whether dependencies were installed during execution.
    </ResponseField>

    <ResponseField name="maxDuration" type="number">
      Maximum duration allowed for the task in seconds.
    </ResponseField>

    <ResponseField name="status" type="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
    </ResponseField>

    <ResponseField name="progress" type="number">
      Task completion percentage (0-100).
    </ResponseField>

    <ResponseField name="error" type="string | null">
      Error message if the task failed.
    </ResponseField>

    <ResponseField name="selectedBranch" type="string">
      The branch that was worked on.
    </ResponseField>

    <ResponseField name="branchName" type="string | null">
      The new branch name created for the task.
    </ResponseField>

    <ResponseField name="sandboxUrl" type="string | null">
      URL to the sandbox environment (if applicable).
    </ResponseField>

    <ResponseField name="sandboxId" type="string | null">
      Identifier for the sandbox environment.
    </ResponseField>

    <ResponseField name="merged" type="boolean">
      Whether the changes have been merged.
    </ResponseField>

    <ResponseField name="diffStats" type="object | null">
      Statistics about code changes made.

      Contains:

      * `totalLinesAdded` - Number of lines added
      * `totalLinesRemoved` - Number of lines removed
      * `totalFilesChanged` - Number of files modified
    </ResponseField>

    <ResponseField name="autoDeployEnabled" type="boolean | null">
      Whether auto-deployment is enabled.
    </ResponseField>

    <ResponseField name="vercelDeploymentSettings" type="object | null">
      Vercel deployment configuration (if applicable).
    </ResponseField>

    <ResponseField name="deployments" type="array | null">
      Array of deployment information.
    </ResponseField>

    <ResponseField name="badge" type="string | null">
      Badge or label associated with the task.
    </ResponseField>

    <ResponseField name="batchId" type="string | null">
      Batch ID if this task is part of a batch.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the task was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp when the task was last updated.
    </ResponseField>

    <ResponseField name="completedAt" type="string | null">
      ISO 8601 timestamp when the task completed.
    </ResponseField>

    <ResponseField name="creatorName" type="string | null">
      Name of the user who created the task.
    </ResponseField>

    <ResponseField name="creatorImage" type="string | null">
      Profile image URL of the task creator.
    </ResponseField>

    <ResponseField name="prNumber" type="number | null">
      Pull request number if a PR was created.
    </ResponseField>

    <ResponseField name="prUrl" type="string | null">
      URL to the pull request if created.
    </ResponseField>

    <ResponseField name="isEmptyGitUser" type="boolean">
      Whether the task was created for a user without GitHub connection.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Indicates if there are more tasks available beyond the current page.
</ResponseField>

<ResponseField name="offset" type="number">
  The offset value used for this request.
</ResponseField>

<ResponseField name="limit" type="number">
  The limit value used for this request.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://cloud.blackbox.ai/api/tasks?limit=50&offset=0&filter=all' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Accept: application/json'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const API_KEY = "YOUR_API_KEY";
  const API_URL = "https://cloud.blackbox.ai/api/tasks";

  // Get first 10 tasks
  const params = new URLSearchParams({
      limit: '10',
      offset: '0',
      filter: 'all'
  });

  const response = await fetch(`${API_URL}?${params}`, {
      method: "GET",
      headers: {
          Authorization: `Bearer ${API_KEY}`,
          Accept: "application/json",
      },
  });

  const data = await response.json();
  console.log(`Retrieved ${data.tasks.length} tasks`);
  console.log(`Has more: ${data.hasMore}`);
  console.log(data.tasks);
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

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

  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Accept": "application/json"
  }

  params = {
      "limit": 10,
      "offset": 0,
      "filter": "all"
  }

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

  print(f"Retrieved {len(data['tasks'])} tasks")
  print(f"Has more: {data['hasMore']}")
  print(data['tasks'])
  ```

  ```go Go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  package main

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

  type TaskResponse struct {
      Tasks   []Task `json:"tasks"`
      HasMore bool   `json:"hasMore"`
      Offset  int    `json:"offset"`
      Limit   int    `json:"limit"`
  }

  type Task struct {
      ID        string `json:"id"`
      Prompt    string `json:"prompt"`
      Status    string `json:"status"`
      CreatedAt string `json:"createdAt"`
      // Add other fields as needed
  }

  func main() {
      apiKey := "YOUR_API_KEY"
      baseURL := "https://cloud.blackbox.ai/api/tasks"

      params := url.Values{}
      params.Add("limit", "10")
      params.Add("offset", "0")
      params.Add("filter", "all")

      fullURL := fmt.Sprintf("%s?%s", baseURL, params.Encode())

      req, _ := http.NewRequest("GET", fullURL, nil)
      req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", apiKey))
      req.Header.Add("Accept", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := io.ReadAll(resp.Body)

      var taskResponse TaskResponse
      json.Unmarshal(body, &taskResponse)

      fmt.Printf("Retrieved %d tasks\n", len(taskResponse.Tasks))
      fmt.Printf("Has more: %v\n", taskResponse.HasMore)
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "tasks": [
      {
        "id": "9qQe2F8Z_nXx9-eJA0BD6",
        "userId": "user@example.com",
        "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": "user@example.com",
        "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
  }
  ```

  ```json Empty Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "tasks": [],
    "hasMore": false,
    "offset": 0,
    "limit": 50
  }
  ```
</ResponseExample>

## Use Cases

### Monitor Active Tasks

Track all currently running tasks:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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                 |