Cancel Task
Stop or cancel a running task. This will terminate the sandbox environment and mark the task as stopped.
PATCH
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
bb_xxxxxxxxxxxxxxxxxxxxxx
Headers
API Key of the form
Bearer <api_key>.Example: Bearer bb_b41b647ffbfed27f61656049d3eaeef3d903cc503345d9eb80080d98bc0Must be
application/json.Path Parameters
The unique identifier of the task you want to cancel.Example:
9qQe2F8Z_nXx9-eJA0BD6Request Body
The action to perform. Must be
"stop" to cancel the task.Response Fields
Success message confirming the task was stopped.
Updated task object with the following fields:
Task identifier.
Email or ID of the user who created the task.
Updated status (will be “stopped”).
Error message explaining the stop (“Task was stopped by user”).
ISO 8601 timestamp of when the task was stopped.
ISO 8601 timestamp when the task was stopped.
Use Cases
Cancel a Long-Running Task
Cancel a task that’s taking too long or is no longer needed:Cancel with Timeout
Automatically cancel a task if it exceeds a certain duration:Python Cancel Example
Cancel Multiple Tasks
Cancel multiple tasks at once:Graceful Shutdown
Implement graceful shutdown when user exits application:Important Notes
-
Only Active Tasks: You can only stop tasks that are currently in
processingorsavingstatus. 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 |