Quickstart

BatchRouter is an OpenAI-Batch-compatible API that routes batch AI workloads across many providers, picking the cheapest lane that meets your SLA, privacy, and tool requirements — with a routing receipt for every decision. This page takes you from zero to your first completed batch in five steps.

The flow is always: quote (free) → create → poll → results. Quotes cost nothing; credits are reserved only when you create a batch and settled from actual token usage.

Before you start

You’ll need an API key and a small credit balance. The base URL is https://api.batchrouter.com (use https://test.api.batchrouter.com for testing), and every endpoint lives under /v1. Authenticate by sending your key as a bearer token:

export BATCHROUTER_API_KEY="br_live_…"

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

That call returns your account, including credit_balance. If it’s zero, you’ll get a 402 on create — add credits from the billing dashboard.

Keep keys server-side

API keys are secrets. Send them only from your backend, never from browsers or mobile clients, and store them in a secrets manager or environment variable.

Walkthrough

1. 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.

   Keys are shown once

   A new key’s full value is returned only at creation time and is never shown again. Copy it immediately and store it securely; if you lose it, create a new one and revoke the old.

   See Authentication for both paths and key rotation.

2. 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

   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-4o-mini",
           "input": {
             "messages": [
               { "role": "user", "content": "Summarize: BatchRouter routes batch-AI workloads across providers." }
             ]
           }
         }
       ]
     }'

   Node

   const res = await fetch("https://api.batchrouter.com/v1/quotes/model", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.BATCHROUTER_API_KEY}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       routing_mode: "cheapest",
       items: [
         {
           customer_item_id: "item-1",
           operation: "responses",
           model: "gpt-4o-mini",
           input: {
             messages: [
               { role: "user", content: "Summarize: BatchRouter routes batch-AI workloads across providers." },
             ],
           },
         },
       ],
     }),
   });
   const quote = await res.json();
   console.log(quote.quote_id, quote.pricing_estimate.total);

   Python

   import os, requests
   
   res = requests.post(
       "https://api.batchrouter.com/v1/quotes/model",
       headers={"Authorization": f"Bearer {os.environ['BATCHROUTER_API_KEY']}"},
       json={
           "routing_mode": "cheapest",
           "items": [
               {
                   "customer_item_id": "item-1",
                   "operation": "responses",
                   "model": "gpt-4o-mini",
                   "input": {
                       "messages": [
                           {"role": "user", "content": "Summarize: BatchRouter routes batch-AI workloads across providers."}
                       ]
                   },
               }
           ],
       },
   )
   quote = res.json()
   print(quote["quote_id"], quote["pricing_estimate"]["total"])

   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.

   gpt-4o-mini is illustrative

   Use real, currently-available model IDs — list them with GET /v1/catalog/models, which also returns per-provider pricing, capacity, regions, and supported hosted tools.

3. 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

   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-4o-mini",
           "input": {
             "messages": [
               { "role": "user", "content": "Summarize: BatchRouter routes batch-AI workloads across providers." }
             ]
           }
         }
       ]
     }'

   Node

   const res = await fetch("https://api.batchrouter.com/v1/batches", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.BATCHROUTER_API_KEY}`,
       "Content-Type": "application/json",
       "Idempotency-Key": "quickstart-batch-001",
     },
     body: JSON.stringify({
       quote_id: "qlock_…",
       sla_tier: "standard",
       items: [
         {
           customer_item_id: "item-1",
           operation: "responses",
           model: "gpt-4o-mini",
           input: {
             messages: [
               { role: "user", content: "Summarize: BatchRouter routes batch-AI workloads across providers." },
             ],
           },
         },
       ],
     }),
   });
   const { batch } = await res.json();
   console.log(batch.id, batch.status); // bat_…  pending

   Python

   import os, requests
   
   res = requests.post(
       "https://api.batchrouter.com/v1/batches",
       headers={
           "Authorization": f"Bearer {os.environ['BATCHROUTER_API_KEY']}",
           "Idempotency-Key": "quickstart-batch-001",
       },
       json={
           "quote_id": "qlock_…",
           "sla_tier": "standard",
           "items": [
               {
                   "customer_item_id": "item-1",
                   "operation": "responses",
                   "model": "gpt-4o-mini",
                   "input": {
                       "messages": [
                           {"role": "user", "content": "Summarize: BatchRouter routes batch-AI workloads across providers."}
                       ]
                   },
               }
           ],
       },
   )
   batch = res.json()["batch"]
   print(batch["id"], batch["status"])  # bat_…  pending

   The response is { "batch": { "id": "bat_…", "status": "pending", "item_count": 1 } }.

   Free quote, credits reserved at create

   Quotes are free. Credits are reserved when this POST /v1/batches call succeeds (using the quote snapshot) and settled afterward from actual provider token usage. A zero balance returns 402 — add credits from the billing dashboard.

4. 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

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

   Node

   const res = await fetch(`https://api.batchrouter.com/v1/batches/${batchId}`, {
     headers: { Authorization: `Bearer ${process.env.BATCHROUTER_API_KEY}` },
   });
   const { batch } = await res.json();
   console.log(batch.status);

   Python

   import os, requests
   
   res = requests.get(
       f"https://api.batchrouter.com/v1/batches/{batch_id}",
       headers={"Authorization": f"Bearer {os.environ['BATCHROUTER_API_KEY']}"},
   )
   print(res.json()["batch"]["status"])

   Status moves through this lifecycle:

   pending → queued → routing → dispatched → processing → completing → completed

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

5. Retrieve your results.

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

   cURL

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

   Node

   const res = await fetch(
     `https://api.batchrouter.com/v1/batches/${batchId}/results?limit=100`,
     { headers: { Authorization: `Bearer ${process.env.BATCHROUTER_API_KEY}` } },
   );
   const { results, next_cursor } = await res.json();
   for (const r of results) {
     console.log(r.customer_item_id, r.status, r.output);
   }

   Python

   import os, requests
   
   res = requests.get(
       f"https://api.batchrouter.com/v1/batches/{batch_id}/results",
       headers={"Authorization": f"Bearer {os.environ['BATCHROUTER_API_KEY']}"},
       params={"limit": 100},
   )
   payload = res.json()
   for r in payload["results"]:
       print(r["customer_item_id"], r["status"], r["output"])

   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.

   Choose your output shape

   Results are normalized (BatchRouter’s unified schema) by default. Request body_format=raw to get each provider’s native output instead.

That’s a complete batch, end to end. From here, scale up with file uploads, point an existing OpenAI Batch client at BatchRouter, or switch from polling to webhooks.

Where to next

Submit a batch Inline vs. file inputs, SLA tiers, routing modes, privacy tiers, and idempotency in depth.

OpenAI compatibility Point your existing OpenAI Batch client's base URL at BatchRouter and keep your code.

Webhooks & delivery Get signed completion events instead of polling, and verify the X-BatchRouter-Signature.

API reference Every endpoint, parameter, and schema for the public /v1 surface.