List Batches

List batch processing runs for document extraction at 50% of realtime cost. Filter by lifecycle status and track item counts, provider, and timing per batch.

Batch processing runs Talonic document extraction through the provider batch API at 50% of the realtime cost, in exchange for deferred results (typically within 24 hours, 48-hour SLA). Documents uploaded with processing_mode=batch run OCR and classification immediately but queue extraction. Batches accumulate items, submit to the provider on a timer or threshold, and poll for results.

Talonic supports two batch providers: the Anthropic Message Batches API (direct) and AWS Bedrock (CreateModelInvocationJob). The provider is auto-detected from your workspace configuration. Results are typically delivered within 24 hours, with a maximum SLA of 48 hours.

Documents run Stage 1 (OCR + classification + triage) immediately on upload.
Stage 2 (Claude extraction) is deferred to the batch API at 50% of standard cost.
Batches require a minimum of 100 items (Bedrock requirement). Smaller uploads fall back to realtime extraction.
Results are polled hourly. Use the sync endpoint to check sooner.

Image-only documents (no text content) cannot enter the batch flow because the text-only batch payload cannot carry image bytes. These are automatically routed to realtime extraction.

GET/v1/batches

Query parameters

statusstringFilter by lifecycle status: `accumulating`, `submitted`, `in_progress`, `completed`, `failed`, `expired`.

limitintegerMaximum number of results to return (1–100). Default: 20

cursorstringPagination cursor from a previous response.

orderstringSort direction by created_at. Default: desc

Response

Response fields

dataarrayArray of batch objects.

data[].idstringBatch UUID.

data[].statusstringBatch status: accumulating, submitted, in_progress, completed, failed, or expired. Manually cancelled batches show cancelled.

data[].providerstringInference provider: anthropic or bedrock.

data[].item_countintegerTotal number of items (documents) in the batch.

data[].succeeded_countintegerNumber of items that completed successfully.

data[].errored_countintegerNumber of items that errored.

data[].expired_countintegerNumber of items that expired before processing.

data[].submitted_atstring | nullISO 8601 timestamp when the batch was submitted to the provider.

data[].completed_atstring | nullISO 8601 timestamp when the batch completed.

data[].error_messagestring | nullProvider error message if the batch failed.

data[].created_atstringISO 8601 creation timestamp.

data[].updated_atstringISO 8601 last update timestamp.

data[].links.selfstringURL to the batch detail endpoint.

pagination.totalintegerTotal number of batches matching the query.

pagination.limitintegerMaximum results per page.

pagination.has_morebooleanWhether more results exist beyond this page.

pagination.next_cursorstring | nullCursor to fetch the next page. Null if no more results.

curl

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed",
      "provider": "anthropic",
      "item_count": 142,
      "succeeded_count": 142,
      "errored_count": 0,
      "expired_count": 0,
      "submitted_at": "2024-10-01T06:00:00.000Z",
      "completed_at": "2024-10-01T14:23:00.000Z",
      "error_message": null,
      "created_at": "2024-10-01T05:45:00.000Z",
      "updated_at": "2024-10-01T14:23:00.000Z",
      "links": { "self": "/v1/batches/a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
    }
  ],
  "pagination": {
    "total": 12,
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Errors

Error responses

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Batch Detail

Sync Batch

Batch Processing Mode

List Batches

Response

Errors

Related