Cancel Task - BLACKBOX AI

This endpoint allows you to stop a task that is currently in progress. When you cancel a task, it will update the task status to stopped, terminate the associated sandbox environment, and mark the task as completed with an error message indicating it was stopped by the user.

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

Content-Type

string

required

Must be application/json.

Path Parameters

taskId

string

required

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

Request Body

action

string

required

The action to perform. Must be "stop" to cancel the task.

Response Fields

message

string

Success message confirming the task was stopped.

task

object

Updated task object with the following fields:

task.id

string

Task identifier.

task.userId

string

Email or ID of the user who created the task.

task.status

string

Updated status (will be “stopped”).

task.error

string

Error message explaining the stop (“Task was stopped by user”).

task.updatedAt

string

ISO 8601 timestamp of when the task was stopped.

task.completedAt

string

ISO 8601 timestamp when the task was stopped.

curl -X PATCH 'https://cloud.blackbox.ai/api/tasks/9qQe2F8Z_nXx9-eJA0BD6' \
  -H 'Authorization: Bearer bb_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"action": "stop"}'

{
  "message": "Task stopped successfully",
  "task": {
    "id": "9qQe2F8Z_nXx9-eJA0BD6",
    "userId": "user@example.com",
    "status": "stopped",
    "error": "Task was stopped by user",
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "completedAt": "2024-01-15T10:30:00.000Z"
  }
}

Use Cases

Cancel a Long-Running Task

Cancel a task that’s taking too long or is no longer needed:

async function cancelTask(taskId) {
  const API_KEY = "bb_YOUR_API_KEY";
  const API_URL = `https://cloud.blackbox.ai/api/tasks/${taskId}`;
  
  try {
    const response = await fetch(API_URL, {
      method: "PATCH",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ action: "stop" }),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || "Failed to cancel task");
    }

    const data = await response.json();
    console.log(data.message); // "Task stopped successfully"
    return data.task;
  } catch (error) {
    console.error("Failed to cancel task:", error.message);
    throw error;
  }
}

// Usage
try {
  const stoppedTask = await cancelTask("9qQe2F8Z_nXx9-eJA0BD6");
  console.log(`Task ${stoppedTask.id} stopped at ${stoppedTask.completedAt}`);
} catch (error) {
  console.error("Error:", error.message);
}

Cancel with Timeout

Automatically cancel a task if it exceeds a certain duration:

async function runTaskWithTimeout(taskId, timeoutMs = 300000) {
  const API_KEY = "bb_YOUR_API_KEY";
  
  // Start monitoring the task
  const timeoutPromise = new Promise((_, reject) => {
    setTimeout(() => reject(new Error("Task timeout")), timeoutMs);
  });
  
  const taskPromise = async () => {
    while (true) {
      const statusResponse = await fetch(
        `https://cloud.blackbox.ai/api/tasks/${taskId}/status`,
        {
          headers: { Authorization: `Bearer ${API_KEY}` },
        }
      );
      const status = await statusResponse.json();
      
      if (status.isDone) {
        return status;
      }
      
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  };
  
  try {
    return await Promise.race([taskPromise(), timeoutPromise]);
  } catch (error) {
    if (error.message === "Task timeout") {
      console.log("Task exceeded timeout, cancelling...");
      await cancelTask(taskId);
      throw new Error("Task was cancelled due to timeout");
    }
    throw error;
  }
}

// Usage
try {
  const result = await runTaskWithTimeout("9qQe2F8Z_nXx9-eJA0BD6", 300000);
  console.log("Task completed:", result);
} catch (error) {
  console.error("Task error:", error.message);
}

Python Cancel Example

import requests

def cancel_task(task_id: str, api_key: str):
    """Cancel a running task"""
    url = f'https://cloud.blackbox.ai/api/tasks/{task_id}'
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    data = {'action': 'stop'}
    
    response = requests.patch(url, headers=headers, json=data)
    
    if response.status_code == 200:
        result = response.json()
        print(f"Task stopped: {result['message']}")
        return result['task']
    else:
        error = response.json()
        raise Exception(error.get('error', 'Failed to cancel task'))

# Usage
try:
    stopped_task = cancel_task('9qQe2F8Z_nXx9-eJA0BD6', 'bb_YOUR_API_KEY')
    print(f"Task {stopped_task['id']} status: {stopped_task['status']}")
except Exception as e:
    print(f"Error: {e}")

Cancel Multiple Tasks

Cancel multiple tasks at once:

async function cancelMultipleTasks(taskIds) {
  const API_KEY = "bb_YOUR_API_KEY";
  
  const cancelPromises = taskIds.map(async (taskId) => {
    try {
      const response = await fetch(
        `https://cloud.blackbox.ai/api/tasks/${taskId}`,
        {
          method: "PATCH",
          headers: {
            Authorization: `Bearer ${API_KEY}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ action: "stop" }),
        }
      );
      
      if (response.ok) {
        const data = await response.json();
        return { taskId, success: true, data };
      } else {
        const error = await response.json();
        return { taskId, success: false, error: error.error };
      }
    } catch (error) {
      return { taskId, success: false, error: error.message };
    }
  });
  
  const results = await Promise.all(cancelPromises);
  
  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);
  
  console.log(`Cancelled ${successful.length} tasks`);
  if (failed.length > 0) {
    console.log(`Failed to cancel ${failed.length} tasks:`, failed);
  }
  
  return results;
}

// Usage
const taskIds = ["task1", "task2", "task3"];
const results = await cancelMultipleTasks(taskIds);

Graceful Shutdown

Implement graceful shutdown when user exits application:

class TaskManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.activeTasks = new Set();
    
    // Handle process termination
    process.on('SIGINT', () => this.shutdown());
    process.on('SIGTERM', () => this.shutdown());
  }
  
  async startTask(taskId) {
    this.activeTasks.add(taskId);
    // ... start task logic
  }
  
  async shutdown() {
    console.log('Shutting down, cancelling active tasks...');
    
    const cancelPromises = Array.from(this.activeTasks).map(taskId =>
      fetch(`https://cloud.blackbox.ai/api/tasks/${taskId}`, {
        method: "PATCH",
        headers: {
          Authorization: `Bearer ${this.apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ action: "stop" }),
      })
    );
    
    await Promise.allSettled(cancelPromises);
    console.log('All tasks cancelled');
    process.exit(0);
  }
}

// Usage
const manager = new TaskManager("bb_YOUR_API_KEY");

Important Notes

Only Active Tasks: You can only stop tasks that are currently in processing or saving status. Completed, failed, or already stopped tasks cannot be stopped again.
Sandbox Termination: The API will attempt to gracefully shutdown all associated sandbox environments. If sandbox termination fails, the task status will still be updated to stopped.
Followup Messages: If the task has active followup messages, the last one will be marked as stopped with an appropriate status message.
Irreversible: Once a task is stopped, it cannot be resumed from where it left off. You would need to create a new task to restart the work.
Error Handling: Always check the response status code. A 400 error indicates the task is not in a state that can be stopped.

Error Codes

Status Code	Error	Description
200	Success	Task stopped successfully
400	Bad Request	Task is not in progress and cannot be stopped
401	Unauthorized	Invalid or missing API key
404	Not Found	Task doesn’t exist or user doesn’t have access
500	Internal Server Error	Server-side error occurred

Endpoints

​Authentication

​Headers

​Path Parameters

​Request Body

​Response Fields

​Use Cases

​Cancel a Long-Running Task

​Cancel with Timeout

​Python Cancel Example

​Cancel Multiple Tasks

​Graceful Shutdown

​Important Notes

​Error Codes

Authentication

Headers

Path Parameters

Request Body

Response Fields

Use Cases

Cancel a Long-Running Task

Cancel with Timeout

Python Cancel Example

Cancel Multiple Tasks

Graceful Shutdown

Important Notes

Error Codes