Manage & monitor batches

Once you've submitted a batch you keep a single batch_id (batch_…) for its whole life. This guide covers the endpoints you use to track, inspect, and manage that batch after creation: listing your batches, polling status, drilling into per-item results, cancelling or retrying, auditing webhook deliveries, and pulling the finalized billing receipt.

All endpoints are under https://api.batchrouter.com/v1 and require Authorization: Bearer br_live_…. For the complete request and response schemas, see the interactive API reference.

List your batchesCopy Anchor Link

GET /v1/batches returns a paginated list of batches in the authenticated workspace, newest first. Filter with state (any batch state, or active for every non-terminal state), page with cursor, and size with limit (1–100, default 20).

Each entry in data is a BatchSummary, which includes id, state, counts (per-item total, pending, running, completed, failed, and canceled), created_at, deadline_at, completed_at, routing_mode, sla_tier, and the output, error, and receipt file ids and signed URLs. The response also carries next_cursor (pass it back as cursor to page) and workspace_total_count.

curl "https://api.batchrouter.com/v1/batches?state=running&limit=20" \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"

To walk every page, keep calling with cursor=<next_cursor> until next_cursor is null.

Get batch statusCopy Anchor Link

GET /v1/batches/{batchId} returns the batch wrapped under a top-level batch key, alongside a billing_receipt (null unless you ask for it). By default it is a lightweight polling view; pass ?include_details=true for the full view, including the work order, workflow contract, and webhook delivery state. With ?include_billing_receipt=true, batch also carries lane_statuses (per-lane status for the internal provider/model executions running under your single batch_id). The latest batch-level execution error, if any, is batch.execution_summary.latest_error.

Poll this endpoint until batch.state reaches a terminal value. The lifecycle runs received → validated → priced → queued → dispatching → running → finalizing → completed; the other terminal states are failed, canceled, and expired. See the status lifecycle reference for what each state means.

curl https://api.batchrouter.com/v1/batches/batch_123 \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"

Prefer event-driven delivery over tight polling. Configure a webhook so BatchRouter notifies you the moment a batch completes, and poll only as a fallback.

Inspect per-item statusCopy Anchor Link

GET /v1/batches/{batchId}/items returns per-item status, errors, and output previews — useful when a batch is partially complete or some items failed and you want to know exactly which ones.

Filter with status (pending, processing, completed, failed), and page with cursor and limit (1–500, default 100). Each item carries customer_item_id (the id you assigned on submit), status, and sequence_number.

curl "https://api.batchrouter.com/v1/batches/batch_123/items?status=failed&limit=100" \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"

Cancel a batchCopy Anchor Link

POST /v1/batches/{batchId}/cancel requests cancellation and returns the updated batch wrapped under batch. A batch that is canceled ends in the terminal canceled state. You can include an optional reason (up to 500 characters) in the JSON body.

Retry a failed batchCopy Anchor Link

POST /v1/batches/{batchId}/retry

curl -X POST https://api.batchrouter.com/v1/batches/batch_123/cancel \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"superseded by a re-run"}'

Review webhook deliveriesCopy Anchor Link

If you configured a webhook (per-batch, or the org default via PUT /v1/auth/account/delivery-webhook), GET /v1/batches/{batchId}/webhooks shows you exactly how delivery is going. It returns the customer-visible delivery status, retry state, last failure details, and persisted delivery events for the batch.

The response (BatchWebhooksResponse) has three top-level fields: batch_id, a data array of delivery records, and an events array of delivery events. Each delivery in data includes:

• url and status — the destination and current state (pending, delivering, succeeded, failed, dead_lettered)
• attempt_count, last_attempt_at, next_attempt_at — retry bookkeeping
• last_response_status and last_error — why the most recent attempt failed, if it did

curl https://api.batchrouter.com/v1/batches/batch_123/webhooks \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"

Audit the billing receiptCopy Anchor Link

Once a batch settles, GET /v1/batches/{batchId}/billing-receipt returns the finalized BatchBillingReceipt. Final cost is settled from actual provider token usage, so the receipt is the authoritative record of what you were charged. It includes:

• final_settled_price, provider_subtotal, and batchrouter_fee
• the credit settlement: credit_reserved, credit_charged, credit_released
• settled_at
• provider_lanes — the quote lanes that actually ran (with the quote-time data/privacy proof for each)
• rejected_lanes — non-selected lanes, each with its rejection receipt

All money values are objects of the form { "currency": "usd", "amount": "1.50" } (a decimal string).

curl https://api.batchrouter.com/v1/batches/batch_123/billing-receipt \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"

Next stepsCopy Anchor Link