Get Task Status

Check the current status of a specific task to see if it’s in progress, completed, or what status it has. This is a lightweight endpoint perfect for polling task progress.

GET /api/tasks/{taskId}/status

cURL

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

Task In Progress

{
  "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
}

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:

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

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

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

Task In Progress

{
  "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 = "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 = "YOUR_API_KEY";
const taskIds = ['task1', 'task2', 'task3'];
const results = await monitorTasks(taskIds, API_KEY);
console.log('All tasks completed:', results);

Polling Best Practices

1. Use Exponential Backoff: Start with short intervals (1-2 seconds) and increase gradually to reduce server load
2. Set Maximum Attempts: Prevent infinite loops by setting a maximum number of polling attempts
3. Handle Network Errors: Implement retry logic for failed requests
4. Consider Webhooks: For production applications, webhooks are more efficient than polling
5. Check isDone Flag: Use the isDone boolean for simple completion checks instead of checking multiple status values
6. 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