Cancel Task

Cancel a task that hasn’t started processing yet

Endpoint

GET /api/v1/task/{task_id}/cancel

Authentication

This endpoint requires API key authentication via the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

task_id · string · required

The unique identifier of the task to cancel

Requirements

• Task must have status Starting
• Tasks that are already Processing, Succeeded, Failed, or Cancelled cannot be cancelled

Response

On success, returns a plain text response:

Task cancelled

Status Codes

• 200: Task cancelled successfully
• 400: Bad request (task cannot be cancelled due to invalid status)
• 404: Task not found or expired
• 500: Internal server error

Behavior

Depending on the task state:

• For new tasks: Status will be updated to Cancelled and processing will never begin
• For updating tasks: Task will revert to its previous state before the update was requested

Examples

cURL

curl -X GET "https://api.chunkr.ai/api/v1/task/123e4567-e89b-12d3-a456-426614174000/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use Cases

1. Accidental Submissions: Cancel tasks that were created by mistake
2. Configuration Errors: Cancel and recreate tasks with corrected settings
3. Queue Management: Cancel low-priority tasks during high-load periods
4. Testing: Cancel test tasks that are no longer needed

Timing Window

Tasks can only be cancelled while they’re in the Starting state, which is typically:

• Right after task creation
• Before worker processes pick up the task
• During the queue waiting period

Once a task moves to Processing state, it cannot be cancelled and must complete or fail naturally.

After Cancellation

Once a task is cancelled:

1. Status changes to Cancelled
2. Message is updated to “Task cancelled”
3. Task will never begin processing
4. Task can be deleted to free up resources
5. Task cannot be restarted - you must create a new task instead

Error Messages

Task not found

The task ID doesn’t exist, has expired, or you don’t have access to it

Task cannot be cancelled

The task is not in Starting state. Common reasons:

• Task is already Processing
• Task has Succeeded or Failed
• Task was already Cancelled

Best Practices

1. Check Status First: Verify the task is in Starting state before attempting to cancel

2. Quick Action: Cancel as soon as you realize the task is not needed, as tasks may move to Processing quickly

3. Create New Tasks: After cancelling, create a new task with correct settings rather than trying to uncancelled

4. Clean Up: Consider deleting cancelled tasks to keep your task list clean

Advanced Example: Cancel and Recreate

import requests
import time

def cancel_and_recreate_task(task_id, new_config, api_key, max_wait=5):
    """Cancel existing task and create a new one with updated config"""
    base_url = "https://api.chunkr.ai/api/v1"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    # Get current task to retrieve original file
    task_response = requests.get(f"{base_url}/task/{task_id}", headers=headers)
    if task_response.status_code != 200:
        return {"error": "Could not retrieve task"}
    
    task = task_response.json()
    
    # Only cancel if in Starting state
    if task['status'] == 'Starting':
        cancel_response = requests.get(
            f"{base_url}/task/{task_id}/cancel",
            headers=headers
        )
        if cancel_response.status_code != 200:
            return {"error": f"Could not cancel: {cancel_response.text}"}
        
        # Wait a moment for cancellation to process
        time.sleep(0.5)
    
    # Create new task with updated configuration
    create_response = requests.post(
        f"{base_url}/task/parse",
        json=new_config,
        headers=headers
    )
    
    if create_response.status_code == 200:
        new_task = create_response.json()
        return {
            "success": True,
            "old_task_id": task_id,
            "new_task_id": new_task['task_id'],
            "message": "Task cancelled and recreated"
        }
    else:
        return {"error": f"Could not create new task: {create_response.text}"}

# Example usage
new_config = {
    "file": "https://example.com/document.pdf",
    "ocr_strategy": "Auto",
    "chunk_processing": {
        "target_length": 1024
    }
}

result = cancel_and_recreate_task(
    "123e4567-e89b-12d3-a456-426614174000",
    new_config,
    "YOUR_API_KEY"
)
print(result)

Related Endpoints

• Delete Task - Permanently delete a Succeeded, Failed, or Cancelled task
• Get Task - Check task status before cancelling
• Create Task - Create a new task to replace the cancelled one