> ## 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.

# List 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:

1. Go to [app.blackbox.ai/agent-api](https://app.blackbox.ai/agent-api) and click **Get an API Key** (requires a Pro subscription)
2. Once provisioning completes, you will be redirected to your [Dashboard](https://app.blackbox.ai/dashboard)
3. 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

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

  Example: `Bearer sk_b41b647ffbfed27f616560`
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination.

  Default: `1`

  Example: `page=2`
</ParamField>

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

  Range: `1` – `100`. Default: `20`.

  Example: `limit=50`
</ParamField>

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

## Response Fields

<ResponseField name="tasks" type="array">
  Array of task run objects.

  <Expandable title="Task Object">
    <ResponseField name="taskId" type="string">
      Unique identifier for the task (same as `runId`).
    </ResponseField>

    <ResponseField name="runId" type="string">
      Unique identifier for this agent run.
    </ResponseField>

    <ResponseField name="chatId" type="string">
      UUID of the chat thread this run belongs to.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: `queued`, `running`, `completed`, `failed`, `cancelled`, or `interrupted`.
    </ResponseField>

    <ResponseField name="model" type="string | null">
      Model used for this run (may be `null`).
    </ResponseField>

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

    <ResponseField name="startedAt" type="string">
      ISO 8601 timestamp when the run started executing. Falls back to `createdAt` if not yet started.
    </ResponseField>

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

    <ResponseField name="assistantMessageId" type="string | null">
      ID of the assistant message generated by this run.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="page" type="number">
  Current page number.
</ResponseField>

<ResponseField name="limit" type="number">
  Number of items per page used for this request.
</ResponseField>

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

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/tasks?page=1&limit=20' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```bash cURL - Filter by Status theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/tasks?status=running&limit=10' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

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

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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']}")
  ```

  ```go Go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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)
  }
  ```
</RequestExample>

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

  ```json Empty Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "tasks": [],
    "page": 1,
    "limit": 20,
    "hasMore": false
  }
  ```

  ```json Error Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Failed to fetch tasks"
  }
  ```
</ResponseExample>

## Use Cases

### Paginate Through All Tasks

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

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