Batchrouter
Start free
API reference

Batches API

Quote, submit, list, and inspect batches over HTTPS. All endpoints accept and return JSON unless noted.

Get an API keyQuickstart
Base URL

api.batchrouter.dev

TLS · JSON · UTF-8

Endpoints

8

3 GET · 5 POST

Quote lock

10 min

price never changes mid-batch

On this page
8 endpoints
POST/v1/quotes/model

Quote with model routing

Pick one model or a set of acceptable models. Batchrouter returns a locked price for the cheapest eligible provider lane (or split across lanes when allowed). Valid for 10 minutes.

shell
curl https://api.batchrouter.dev/v1/quotes/model \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["gpt-4o-mini", "claude-haiku-4"],
    "task": "responses",
    "estimated_items": 50000,
    "routing_mode": "cheapest",
    "privacy_tier": "standard",
    "allowed_regions": ["global"]
  }'
POST/v1/quotes/workflow

Quote a workflow

Buy the outcome of a curated workflow (classification, extraction, embeddings, etc.) instead of choosing a model. Batchrouter picks the provider and model mix that satisfies the workflow contract.

shell
curl https://api.batchrouter.dev/v1/quotes/workflow \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow":"classify-support-tickets@v3","estimated_items":12000}'
POST/v1/batches/input-manifests

Upload an input manifest

For production-scale batches, upload a JSONL manifest and reference it by file_id when creating the batch. Avoids multi-GB request bodies.

shell
curl https://api.batchrouter.dev/v1/batches/input-manifests \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY" \
  -F "file=@batch.jsonl"
POST/v1/batches

Submit a batch

Create a batch from inline items or an uploaded input_file_id. Supply a webhook (url + signing secret) to receive completion events. Returns a batch object with id, state, and pricing_estimate.

shell
curl https://api.batchrouter.dev/v1/batches \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "qlock_...",
    "input_file_id": "file_...",
    "routing_mode": "cheapest",
    "privacy_tier": "standard",
    "webhook": { "url": "https://example.com/hook", "secret": "whsec_..." }
  }'
GET/v1/batches

List batches

Returns recent batches in reverse chronological order. Supports cursor pagination via the after query parameter.

shell
curl https://api.batchrouter.dev/v1/batches \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"
GET/v1/batches/:id

Retrieve a batch

Fetch the current status, settled vs quoted total, per-lane breakdown, and routing explanation for a single batch.

shell
curl https://api.batchrouter.dev/v1/batches/batch_123 \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"
GET/v1/batches/:id/artifact-url

Get a signed artifact URL

Returns a short-lived signed R2 URL to download the completed output file. Issued only after the batch reaches the succeeded state.

shell
curl https://api.batchrouter.dev/v1/batches/batch_123/artifact-url \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"
POST/v1/batches/:id/cancel

Cancel a batch

Stops further routing. Items already submitted to a provider may still complete and be billed.

shell
curl -X POST https://api.batchrouter.dev/v1/batches/batch_123/cancel \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"

Ship your first batch

Mint a key, post one JSONL file, and let the cheapest eligible lane win.

← Back to docsStart free