Get Task Status - BLACKBOX AI

This endpoint allows you to check the current status of a task without retrieving the full task object. It’s optimized for frequent polling and returns only essential status information including progress percentage, completion state, and any errors.

Authentication

Required - You need a BLACKBOX API Key to use this API. Follow these steps to get your API key:

Click on your Profile Image in the top right corner at cloud.blackbox.ai
Click on “BLACKBOX API Token” from the dropdown menu
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

Path Parameters

taskId

string

required

The unique identifier of the task you want to check the status for.Example: 9qQe2F8Z_nXx9-eJA0BD6

Response Fields

taskId

string

Task identifier.

status

string

Current status of the task.Possible values:

pending - Task is queued and waiting to start
processing - Task is currently being executed
saving - Task is saving changes
completed - Task finished successfully
error - Task failed with an error
stopped - Task was manually stopped by user
timeout - Task exceeded maximum duration

progress

number

Progress percentage (0-100).

inProgress

boolean

Whether task is currently running (pending/processing/saving).

isDone

boolean

Whether task has finished (completed/error/stopped/timeout).

error

string | null

Error message if task failed, null otherwise.

createdAt

string

ISO 8601 timestamp when task was created.

updatedAt

string

ISO 8601 timestamp of last update.

completedAt

string | null

ISO 8601 timestamp when task completed, null if still running.

duration

string | null

Task duration in seconds (e.g., “900s”) if completed, null otherwise.

curl 'https://cloud.blackbox.ai/api/tasks/9qQe2F8Z_nXx9-eJA0BD6/status' \
  -H 'Authorization: Bearer bb_YOUR_API_KEY' \
  -H 'Accept: application/json'

{
  "taskId": "9qQe2F8Z_nXx9-eJA0BD6",
  "status": "processing",
  "progress": 45,
  "inProgress": true,
  "isDone": false,
  "error": null,
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:05:00.000Z",
  "completedAt": null,
  "duration": null
}

Use Cases

Polling for Task Completion

Poll task status until completion with simple logic:

async function waitForTaskCompletion(taskId, apiKey) {
  const API_URL = `https://cloud.blackbox.ai/api/tasks/${taskId}/status`;
  
  while (true) {
    const response = await fetch(API_URL, {
      headers: {
        Authorization: `Bearer ${apiKey}`
      }
    });
    const status = await response.json();
    
    console.log(`Task ${taskId}: ${status.status} (${status.progress}%)`);
    
    if (status.isDone) {
      if (status.status === 'completed') {
        console.log(`Task completed in ${status.duration}`);
        return status;
      } else {
        throw new Error(`Task failed: ${status.error}`);
      }
    }
    
    // Wait 2 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

// Usage
const API_KEY = "bb_YOUR_API_KEY";
try {
  const result = await waitForTaskCompletion('9qQe2F8Z_nXx9-eJA0BD6', API_KEY);
  console.log('Task completed successfully!');
} catch (error) {
  console.error('Task failed:', error.message);
}

Polling with Exponential Backoff

Implement exponential backoff to reduce server load:

async function pollTaskStatus(
  taskId,
  apiKey,
  maxAttempts = 100,
  initialDelay = 1000
) {
  const API_URL = `https://cloud.blackbox.ai/api/tasks/${taskId}/status`;
  let attempts = 0;
  let delay = initialDelay;
  
  while (attempts < maxAttempts) {
    try {
      const response = await fetch(API_URL, {
        headers: {
          Authorization: `Bearer ${apiKey}`
        }
      });
      const status = await response.json();
      
      console.log(`Attempt ${attempts + 1}: ${status.status} (${status.progress}%)`);
      
      if (status.isDone) {
        return status;
      }
      
      // Exponential backoff: double delay each time, max 30 seconds
      await new Promise(resolve => setTimeout(resolve, delay));
      delay = Math.min(delay * 2, 30000);
      attempts++;
      
    } catch (error) {
      console.error('Polling error:', error);
      await new Promise(resolve => setTimeout(resolve, delay));
      attempts++;
    }
  }
  
  throw new Error('Max polling attempts reached');
}

Python Polling Example

import requests
import time

def wait_for_task_completion(task_id: str, api_key: str = None):
    """Poll task status until completion"""
    url = f'https://cloud.blackbox.ai/api/tasks/{task_id}/status'
    headers = {}
    if api_key:
        headers['Authorization'] = f'Bearer {api_key}'
    
    while True:
        response = requests.get(url, headers=headers)
        status = response.json()
        
        print(f"Task {task_id}: {status['status']} ({status['progress']}%)")
        
        if status['isDone']:
            if status['status'] == 'completed':
                print(f"Task completed in {status['duration']}")
                return status
            else:
                raise Exception(f"Task failed: {status['error']}")
        
        # Wait 2 seconds before next poll
        time.sleep(2)

# Usage
try:
    result = wait_for_task_completion('9qQe2F8Z_nXx9-eJA0BD6')
    print('Task completed successfully!')
except Exception as e:
    print(f'Task failed: {e}')

Monitoring Multiple Tasks

Monitor multiple tasks simultaneously:

async function monitorTasks(taskIds, apiKey) {
  const statuses = new Map();
  
  const checkTask = async (taskId) => {
    const response = await fetch(
      `https://cloud.blackbox.ai/api/tasks/${taskId}/status`,
      {
        headers: {
          Authorization: `Bearer ${apiKey}`
        }
      }
    );
    return response.json();
  };
  
  while (taskIds.length > 0) {
    const results = await Promise.all(
      taskIds.map(id => checkTask(id))
    );
    
    results.forEach((status, index) => {
      const taskId = taskIds[index];
      console.log(`${taskId}: ${status.status} (${status.progress}%)`);
      
      if (status.isDone) {
        statuses.set(taskId, status);
        taskIds.splice(index, 1);
      }
    });
    
    if (taskIds.length > 0) {
      await new Promise(resolve => setTimeout(resolve, 3000));
    }
  }
  
  return statuses;
}

// Usage
const API_KEY = "bb_YOUR_API_KEY";
const taskIds = ['task1', 'task2', 'task3'];
const results = await monitorTasks(taskIds, API_KEY);
console.log('All tasks completed:', results);

Polling Best Practices

Use Exponential Backoff: Start with short intervals (1-2 seconds) and increase gradually to reduce server load
Set Maximum Attempts: Prevent infinite loops by setting a maximum number of polling attempts
Handle Network Errors: Implement retry logic for failed requests
Consider Webhooks: For production applications, webhooks are more efficient than polling
Check isDone Flag: Use the isDone boolean for simple completion checks instead of checking multiple status values
Respect Rate Limits: Avoid polling too frequently; 2-5 second intervals are generally appropriate

Status Values Reference

Status	Description	inProgress	isDone
`pending`	Task is queued and waiting to start	true	false
`processing`	Task is currently being executed	true	false
`saving`	Task is saving changes	true	false
`completed`	Task finished successfully	false	true
`error`	Task failed with an error	false	true
`stopped`	Task was manually stopped by user	false	true
`timeout`	Task exceeded maximum duration	false	true

Error Codes

Status Code	Error	Description
200	Success	Task status retrieved successfully
401	Unauthorized	Invalid or missing API key
404	Not Found	Task not found or user does not have access to the task
500	Internal Server Error	Database error occurred while fetching task status

Endpoints

​Authentication

​Headers

​Path Parameters

​Response Fields

​Use Cases

​Polling for Task Completion

​Polling with Exponential Backoff

​Python Polling Example

​Monitoring Multiple Tasks

​Polling Best Practices

​Status Values Reference

​Error Codes

Authentication

Headers

Path Parameters

Response Fields

Use Cases

Polling for Task Completion

Polling with Exponential Backoff

Python Polling Example

Monitoring Multiple Tasks

Polling Best Practices

Status Values Reference

Error Codes