Skip to main content

Cancel Batch

Cancel an in-flight extraction batch while it is accumulating or submitted. Documents revert to batch_queued status and can be reprocessed in realtime mode.

Cancel a batch that is still accumulating or submitted to stop deferred extraction for its documents. Cancellation sends a stop request to the provider if the batch was already submitted. Documents in the cancelled batch revert to batch_queued status and can be resubmitted or processed via realtime extraction.

Use cancellation when you need to abort a batch — for example, if documents were submitted with an incorrect schema or you need results faster via realtime extraction. Cancel as early as possible; items already processed by the provider before the cancellation lands may still have their results applied.

The response returns the batch with status: cancelled. The succeeded_count may be non-zero if some items were processed before cancellation took effect. Documents revert to batch_queued status and can be re-processed by updating their processing_mode to realtime or by including them in a new batch.

Only batches in accumulating or submitted status can be cancelled: calling cancel on a completed, failed, or already cancelled batch returns 409 Conflict. Pair with GET /v1/batches/{id} after cancellation to inspect which items were processed before the stop request landed.

POST/v1/batches/{id}/cancel

Path parameters

id*uuidBatch UUID.
Cancelling a submitted batch sends a cancellation request to the provider. Items already processed by the provider may still have their results applied.

curl

curl -s -X POST https://api.talonic.com/v1/batches/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

idstringBatch UUID.
statusstringAlways `cancelled` on success.
providerstringInference provider.
item_countintegerTotal number of items in the batch.
succeeded_countintegerNumber of items that completed before cancellation.
errored_countintegerNumber of items that errored.
expired_countintegerNumber of items that expired.
submitted_atstring | nullISO 8601 timestamp when the batch was submitted.
completed_atstring | nullNull for cancelled batches.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 timestamp of the cancellation.
links.selfstringURL to this batch.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "cancelled",
  "provider": "anthropic",
  "item_count": 37,
  "succeeded_count": 0,
  "errored_count": 0,
  "expired_count": 0,
  "submitted_at": null,
  "completed_at": null,
  "error_message": null,
  "created_at": "2024-10-02T08:10:00.000Z",
  "updated_at": "2024-10-02T09:15:00.000Z",
  "links": { "self": "/v1/batches/a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
404not_foundNo batch with this ID exists for your organization.
409conflictBatch is not in a cancellable status. Only accumulating or submitted batches can be cancelled.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

Can I cancel a completed batch?+
No. Only batches in accumulating or submitted status can be cancelled. Completed, failed, and already-cancelled batches return a 409 Conflict error.
What happens to documents after cancellation?+
Documents revert to batch_queued status. You can resubmit them in a new batch or process them via realtime extraction by updating their processing_mode.
Will cancellation stop items the provider already processed?+
No. Items the provider finished before the stop request landed may still have their results applied, so succeeded_count can be non-zero on a cancelled batch. Cancel as early as possible.

Related

List Batches
Batch Detail
Sync Batch