FAQ

Common questions developers ask when integrating the BatchRouter API. Each answer links to the guide or reference page with the full detail. For the complete endpoint list, see the interactive API reference.

How is BatchRouter different from calling a provider directly?Copy Anchor Link

When you call a provider's batch API directly, you pick the provider, the model, and the SLA window yourself — and you re-implement that integration for every provider you want to use. BatchRouter is a routing layer in front of many providers: you submit a batch once, BatchRouter quotes the work and routes it to the cheapest eligible provider lane that satisfies your model, deadline, capacity, and privacy requirements, then tracks execution, delivery, and billing through one API and one credit balance.

Concretely, BatchRouter adds:

• One API and one key across all providers (no per-provider integration).
• Quote-first pricing — you see the price before you commit (see below).
• SLA-aware lanes — every batch is routed against one 24-hour SLA.
• Routing receipts — every quote explains why a lane was chosen, and rejected lanes carry a reason, so routing is auditable.
• Privacy controls — privacy_tier (standard · confidential · restricted) and routing_mode constrain which providers are eligible.
• Direct and batch through one API — send a single request to POST /v1/chat/completions for an answer right away, or queue it at the batch price.

See Core concepts for the routing model and Routing modes for how lanes are selected.

Can I send a single request and get the answer right away?Copy Anchor Link

Yes. POST /v1/chat/completions takes a standard OpenAI chat completions body and answers directly; "stream": true streams the answer as server-sent events. Point an OpenAI SDK at https://api.batchrouter.com/v1 with your BatchRouter key.

If the answer can wait, add "batch": true. The request is queued as a one-item batch at the lower batch price, the call returns 202 with a job ID, and you poll GET /v1/chat/completions/{id} or get a webhook. See Chat completions.

Is BatchRouter OpenAI-Batch compatible?Copy Anchor Link

Yes. BatchRouter exposes an OpenAI-Batch-shaped surface under /v1/openai/v1/* so you can point an existing OpenAI Batch client at BatchRouter by changing the base URL and key. The compatible endpoints are:

• POST /v1/openai/v1/files and GET /v1/openai/v1/files/{fileId} (+ /content) — upload and read JSONL files.
• POST /v1/openai/v1/batches, GET /v1/openai/v1/batches, GET /v1/openai/v1/batches/{batchId} — create, list, and poll batches.
• POST /v1/openai/v1/batches/{batchId}/cancel — cancel.

# Point an OpenAI Batch client at BatchRouter
curl https://api.batchrouter.com/v1/openai/v1/batches \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_...",
    "endpoint": "/v1/responses",
    "completion_window": "24h"
  }'

How is pricing calculated?Copy Anchor Link

Pricing is quote-first and settled from usage:

1. Quote (free). Call POST /v1/quotes/model (a direct route — one or several acceptable models) or POST /v1/quotes/workflow (a curated workflow product). The quote is free, returns a quote_id, an expiration, and the selected lane(s) and price. Quotes are versioned snapshots, so the price you see is the price you commit to.
2. Reserve at create. When you create the batch with POST /v1/batches (passing the quote_id), BatchRouter reserves credits against your prepaid balance for the quoted amount.
3. Settle from actual usage. After execution, the batch is settled from real provider usage and the reservation is reconciled. Per-batch costs are itemized on the billing receipt at GET /v1/batches/{batchId}/billing-receipt, and platform fees are described by GET /v1/pricing/fees.

See Quotes and pricing and Credits and billing.

What happens if I don't have enough credits (402)?Copy Anchor Link

Credits are prepaid. If your balance can't cover a batch's reservation, the create request is rejected with 402 Payment Required rather than running and overdrawing your account — the funding gate is checked before any work is dispatched. POST /v1/quotes/model, POST /v1/quotes/workflow, and POST /v1/batches can all return 402.

To recover, top up your balance in the dashboard at batchrouter.com/app/billing, then retry the create. There is no public billing-checkout endpoint — credits are purchased in the dashboard.

How long are my results kept?Copy Anchor Link

Results retention is controlled per-org by GET|PUT /v1/retention-settings. The default is the free grace_only tier — results are downloadable for a short grace window after completion, then garbage collected. The available retention_tier values are:

• grace_only — free; download within the grace window.
• extended_fixed — keep results for a fixed extended_days window. Metered (a storage charge against your prepaid balance) once storage fees are enabled.
• until_deleted — keep until you delete. Also metered when storage fees are enabled.

Set never_charge: true to guarantee zero storage spend (this forces the free grace_only tier). Once retention reclaims the bytes, a result file persists as expired (distinct from a 404 that never existed) and its content endpoint returns 410.

Download results while they're available via GET /v1/batches/{batchId}/results (paginated) or a signed URL from GET /v1/batches/{batchId}/artifact-url. See Retrieving results and Retention.

Can I cancel a batch?Copy Anchor Link

Yes — POST /v1/batches/{batchId}/cancel requests cancellation. Whether a batch can still be cancelled depends on its current state: a batch already in a terminal state (completed, failed, canceled, expired) cannot be cancelled. See the API reference for the exact state transitions.

Can I retry a batch?Copy Anchor Link

Yes. There are two distinct operations:

• POST /v1/batches/{batchId}/retry — creates a new batch from the failed and canceled items of a finished batch. Only available once the batch is in a terminal state, and only if it has failed or canceled items. (Beta — behaviour may change.)
• POST /v1/batches/{batchId}/redeliver — re-enqueue delivery to your configured customer bucket when a delivery failed. This is guarded against double-delivery (it returns 409 if the batch is already delivered or delivering) and requires a configured delivery target.

See the Batches reference for the full lifecycle.

How do I get notified when a batch finishes?Copy Anchor Link

Three options, in order of how hands-off they are:

1. Poll. Call GET /v1/batches/{batchId} and watch batch.state move received → validated → priced → queued → dispatching → running → finalizing → completed (other terminal states: failed · canceled · expired). Simplest to integrate; good for scripts and short jobs.
2. Webhook. Set a per-batch { url, secret } at create time, or an org-wide default with PUT /v1/auth/account/delivery-webhook. BatchRouter signs every webhook with an X-BatchRouter-Signature header (HMAC-SHA256) — verify it before trusting the payload. Inspect delivery attempts with GET /v1/batches/{batchId}/webhooks.
3. Delivery target. Configure a customer-owned destination (e.g. your own bucket) with GET|POST /v1/delivery-targets, test it with POST /v1/delivery-targets/{id}/test, and BatchRouter delivers results there directly.

See Webhooks and delivery for signature verification and payloads.

Which models and providers are available?Copy Anchor Link

The catalog is live — query it rather than hardcoding model names:

• Models — GET /v1/catalog/models (list) and GET /v1/catalog/models/{slug} (detail).
• Workflow products — GET /v1/catalog/workflow-products and .../{slug}.
• Providers — GET /v1/providers (list) and GET /v1/providers/{slug} (detail).

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

Next stepsCopy Anchor Link