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)
}
{
"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"
}
Tasks
List Tasks
Retrieve a paginated list of your agent task runs with optional status filtering.
GET
/
api
/
v1
/
tasks
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)
}
{
"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"
}
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
sk-xxxxxxxxxxxxxxxxxxxxxx
Headers
string
required
API Key of the form
Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560Query Parameters
integer
default:"1"
Page number for pagination.Default:
1Example: page=2integer
default:"20"
Number of tasks to return per page.Range:
1 – 100. Default: 20.Example: limit=50string
Filter tasks by status. If omitted, all statuses are returned.Available values:
queued— Task is waiting to startrunning— Task is actively executingcompleted— Task finished successfullyfailed— Task encountered an errorcancelled— Task was cancelled by userinterrupted— Task was interrupted
status=runningResponse Fields
array
Array of task run objects.
Show Task Object
Show Task Object
string
Unique identifier for the task (same as
runId).string
Unique identifier for this agent run.
string
UUID of the chat thread this run belongs to.
string
Current status:
queued, running, completed, failed, cancelled, or interrupted.string | null
Model used for this run (may be
null).string
ISO 8601 timestamp when the run was created.
string
ISO 8601 timestamp when the run started executing. Falls back to
createdAt if not yet started.string | null
ISO 8601 timestamp when the run completed.
string | null
ID of the assistant message generated by this run.
number
Current page number.
number
Number of items per page used for this request.
boolean
Whether there are more tasks beyond the current page.
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)
}
{
"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 |