Cancel Batch
Cancel a batch job using POST /v1/batch/:id/cancel.
Cancel Batch
Cancel a batch job that is pending or processing.
POST
/v1/batch/:id/cancelCancel a batch job. Items that have already completed will not be affected.
Path Parameters
Parameters
| Parameter | Type | Description |
|---|
Example Request
Response
Success Response (200)
{
"id": "batch_abc123def456",
"status": "cancelled",
"message": "Batch cancelled successfully"
}Error Responses
400 Bad Request (already completed or cancelled)
{
"error": {
"code": "CANNOT_CANCEL",
"message": "Cannot cancel batch. Batch not found or already completed/cancelled."
}
}404 Not Found
{
"error": {
"code": "not_found",
"message": "Batch not found"
}
}Cancellation Behavior
When a batch is cancelled:
- Pending items - Marked as
skipped, will not be processed - Queued items - Removed from queue, marked as
skipped - Processing items - May complete if already started
- Completed items - Remain unchanged, results available
Cancellation is best-effort. Items that have already started processing may complete before the cancellation takes effect. You will only be charged for items that complete verification.
Use Cases
Cancel on High Error Rate
async function monitorAndCancel(client, batchId) {
const batch = await client.getBatch(batchId);
// Cancel if failure rate exceeds 20%
const failureRate = batch.failureCount / batch.processedItems;
if (failureRate > 0.2 && batch.processedItems > 10) {
console.log('High failure rate detected, cancelling batch...');
await client.cancelBatch(batchId);
}
}Cancel with Timeout
async function runBatchWithTimeout(client, request, timeoutMs = 300000) {
const batch = await client.createBatch(request);
const timeout = setTimeout(async () => {
console.log('Batch timeout, cancelling...');
await client.cancelBatch(batch.id);
}, timeoutMs);
try {
return await client.getBatch(batch.id); // Poll until complete
} finally {
clearTimeout(timeout);
}
}