Monitoring Batches

The Batches page at /sources/batches shows the status of all batches with real-time updates. On the happy path a batch progresses through accumulating (items collecting in the queue), submitted (sent to the provider's batch API), in progress (the provider is working through the items), and completed (results received and applied to the corresponding documents). Two terminal states cover problems: failed and expired. The page live-syncs with the provider so you can monitor progress without manual refreshing. Click any batch to see the detail view with individual items, their processing state, and any errors.

Batches are submitted automatically when the accumulation timer fires (every 15 minutes by default) or when the item count threshold is reached, whichever comes first. These intervals are configurable in the pipeline settings. Once submitted, the platform polls the provider hourly to check for completion. When results arrive, they are applied to the corresponding documents — including field resolution, linking, triage, and delivery events — and the batch transitions to completed status.

The batch detail view shows individual items within a batch, including which documents are included, their current processing state, and any errors that occurred. Use this view to verify that a specific document was included in the expected batch and to troubleshoot items that failed to parse.

For example, after uploading 500 invoices in batch mode, navigate to /sources/batches to check progress. You will see a batch in accumulating status collecting items until the 15-minute timer fires. Once submitted, the status changes to submitted and the platform polls the provider hourly. Click the batch row to see each document's individual state — if 3 items show parse errors, those documents were automatically retried via the real-time path while the remaining 497 completed normally. When the batch transitions to completed, all results have been applied and documents are ready for review.

The platform includes built-in crash recovery for batch processing. If the application restarts while a batch is in a transient processing state, the recovery logic automatically reverts it to submitted so the next polling cycle can retry. This means batches are resilient to infrastructure disruptions without requiring manual intervention.

# List all batches, optionally filtered by status:
curl -s "https://api.talonic.com/v1/batches?status=submitted" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Get detail for a specific batch including per-item states:
curl -s https://api.talonic.com/v1/batches/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response:
# {
#   "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
#   "status": "completed",
#   "provider": "anthropic",
#   "item_count": 150,
#   "succeeded_count": 147,
#   "errored_count": 3,
#   "expired_count": 0,
#   "submitted_at": "2026-04-22T10:15:00Z",
#   "completed_at": "2026-04-22T14:02:00Z",
#   "items": [
#     {
#       "id": "0a1b2c3d-4e5f-6789-0abc-def123456789",
#       "document_id": "f0e1d2c3-b4a5-9687-8765-432109876543",
#       "document_filename": "invoice-042.pdf",
#       "status": "completed",
#       "error_message": null,
#       "created_at": "2026-04-22T09:58:00Z",
#       "processed_at": "2026-04-22T14:01:30Z"
#     }
#   ]
# }

The batch detail view is your primary tool for diagnosing issues with batch processing. Each item shows its individual status, an error_message when something went wrong, and a processed_at timestamp once its result is applied. Items whose extraction fails to parse are retried through the real-time extraction path (never as a new batch), which keeps the original 48-hour SLA intact. If a batch has an unusually high error rate, this may indicate a problem with the documents themselves (corrupt files, unusual formatting) rather than a system issue. The crash recovery mechanism ensures that infrastructure disruptions such as application restarts, memory pressure, or network interruptions do not leave batches in a permanently stuck state.