Quickstart

Create an API key.

Create a key in the dashboard or, for an agent-first flow with no email, call POST /v1/auth/agent-register to get an org_id and api_key in one shot.

See Authentication for both paths and key rotation.

Get a free quote.

Send your items to POST /v1/quotes/model. BatchRouter prices the work, picks a lane, and returns a quote_id (qlock_…) plus a per-lane breakdown. Quoting is free and reserves nothing.

curl https://api.batchrouter.com/v1/quotes/model \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing_mode": "cheapest",
    "items": [
      {
        "customer_item_id": "item-1",
        "operation": "responses",
        "model": "gpt-5.4-mini",
        "input": {
          "messages": [
            { "role": "user", "content": "Summarize: BatchRouter routes batch-AI workloads across providers." }
          ]
        }
      }
    ]
  }'

The response includes quote_id, a pricing_estimate (provider_subtotal, batchrouter_fee, customer_discount, total), the selected quote_lanes, and a plain-language customer_explanation. Unselected lanes come back with rejection reasons such as capacity_full, context_window_exceeded, or tool_support.

Submit your first batch.

Pass the quote_id to POST /v1/batches and include an Idempotency-Key header (8–128 chars) so retries never create a duplicate. A 202 means it's accepted and queued.

curl https://api.batchrouter.com/v1/batches \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-batch-001" \
  -d '{
    "quote_id": "qlock_…",
    "sla_tier": "standard",
    "items": [
      {
        "customer_item_id": "item-1",
        "operation": "responses",
        "model": "gpt-5.4-mini",
        "input": {
          "messages": [
            { "role": "user", "content": "Summarize: BatchRouter routes batch-AI workloads across providers." }
          ]
        }
      }
    ]
  }'

The response is { "batch": { "id": "batch_…", "state": "priced", "counts": { "total": 1, … } } }.

Poll for status.

Fetch the batch until it reaches a terminal state. Add ?include_billing_receipt=true once it's done to see the final cost.

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

state moves through this lifecycle:

received → validated → priced → queued → dispatching → running → finalizing → completed

Terminal states are completed, failed, canceled, and expired. Poll on an interval (e.g. every 30–60s); to avoid polling entirely, attach a webhook at create time.

Retrieve your results.

Once state is completed, read the output. GET /v1/batches/{batchId}/results returns one entry per item, paginated.

curl "https://api.batchrouter.com/v1/batches/batch_…/results?limit=100" \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"

Each result has customer_item_id, status (completed or failed), output, and error. Page with ?cursor=<next_cursor> (limit 1–1000, default 100). For large batches, prefer GET /v1/batches/{batchId}/artifact-url, which returns a short-lived signed url to the full JSONL artifact instead of paginating.