Analyze 10,000 documents overnight.
Async batch routing at ~50% the realtime cost. Structured JSON extraction. SQLite-backed progress + failure recovery. ~120 lines of Python.
Architecture — Two scripts + SQLite
- enqueue.py — iterates a directory of docs, fires one batch request per doc, records the job_id in SQLite. Idempotent: re-running skips already-queued docs.
- poll_results.py — background worker that polls all
queuedjobs every 30 s, persists results + errors. Stops when no queued rows remain. - SQLite — single-file state. No Redis, no Postgres needed for this scale.
Why batch: at 10,000 documents averaging 5,000 tokens each, realtime costs roughly twice as much as batch. The SLA is 15-30 minutes per doc, but we don't care — we're running overnight.
1. Define the output — JSON schema for the model
We use response_format: json_object + an inline schema in the system prompt. For stricter validation, switch to response_format: json_schema with the same shape — supported on most newer models.
Output schema
2. Enqueue — Fire batch requests
Enqueue every doc
Run this once. It walks the directory, queues every doc, exits. SQLite remembers what's queued — safe to re-run.
3. Poll for completions — Background poller
Polls every queued job every 30 s. Records results to SQLite. Records errors to SQLite. Exits when no more queued rows.
Background poller
4. Progress report — See where you are
Run anytime to check % done + cumulative batch savings.
Progress report
Production tips
- Webhook over polling — for >1,000 docs, configure the
batch.completedwebhook (see /docs/webhooks) and skip the poller. Anoman pushes results when ready. - Per-doc retries — if a doc fails with
guardrail_error(PII redaction wiped too much content), retry with thex-anoman-policy-groupheader pointing at a more permissive policy group. - Long docs — for >50K-token documents, chunk and run multiple batch jobs per doc, then merge results. Cheaper than realtime-with-long-context.
- Cost cap — set a per-key monthly budget. Runaway pipelines hit 402 instead of draining you.
- Auto-promotion to realtime — Anoman auto-promotes batch jobs at 80% SLA. You won't miss the deadline, but you stop saving on those specific jobs. Surfaces in the trace.
See batch economics in the dashboard.
Per-day savings broken down by model.