Control Batch State¶

PUT https://api.wickson.ai/v1/batches/{batch_id}/state

Description¶

Controls the execution state of a batch processing job. Currently, this endpoint supports cancellation of in-progress batch jobs.

Path Parameters¶

batch_id: Required. The unique identifier for the batch you want to control.

Request Body¶

The request body is optional as the endpoint currently only supports cancellation.

Example Request¶

curl -X PUT \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.wickson.ai/v1/batches/batch-abc123/state"

Python Example¶

import requests

# Configuration
api_key = "YOUR_API_KEY"
batch_id = "batch-abc123"

# Cancel the batch
response = requests.put(
    f"https://api.wickson.ai/v1/batches/{batch_id}/state",
    headers={
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    }
)

# Process the response
if response.status_code == 200:
    data = response.json()
    result = data["data"]
    print(f"Batch {result['batch_id']} state changed:")
    print(f"  {result['previous_state']} -> {result['current_state']}")
    print(f"  Timestamp: {result['timestamp']}")
else:
    print(f"Error {response.status_code}: {response.text}")

Response¶

Success Response (200 OK)¶

{
  "success": true,
  "message": "Batch cancelled successfully",
  "data": {
    "batch_id": "batch-abc123",
    "previous_state": "running",
    "current_state": "cancelled",
    "timestamp": "2024-12-18T12:30:00Z"
  }
}

Error Responses¶

Batch Not Found (404 Not Found)¶

{
  "success": false,
  "message": "Batch batch-xyz789 not found",
  "code": "not_found",
  "status_code": 404
}

Processing Error (500 Internal Server Error)¶

{
  "success": false,
  "message": "Failed to cancel batch: Backend service unavailable",
  "code": "processing_error",
  "status_code": 500,
  "details": {
    "operation": "cancel_batch",
    "batch_id": "batch-abc123"
  }
}

Notes¶

Cancelling a batch will stop all pending jobs and terminate any currently processing jobs. Completed jobs will remain unaffected.
Once a batch is cancelled, it cannot be resumed.
All files that were already processed will have their results preserved and accessible.