Bulk document processing with the API
Convert, compress or OCR hundreds of files: choose between batch jobs and bulk workflow runs, stay inside plan limits and retry only what failed.
Short answer
For a one-step conversion of up to 20 files per call, use POST /api/v1/jobs/batch/ with a "jobs" array and follow GET /api/v1/jobs/batch/{batchId}/. For several steps per file, create a workflow and start it with "mode": "each" on up to 100 documents per call. Give every call a stable Idempotency-Key so a retry only starts what is missing.
Pick the right tool
On the Free plan every processing call counts as one request against 10 a day, so bulk work needs a paid plan or purchased credits.
| Job | Use | Per call |
|---|---|---|
| Same conversion for many files (DOCX → PDF) | POST /jobs/batch/ | 1–20 files, 2 credits per batch |
| Several steps per file (convert, compress, rotate) | Workflow + runs with mode "each" | 1–100 documents, 3 credits per run |
| Combine many files into one (merge) | Workflow + runs with mode "together" | up to 100 documents in one run |
| Video and audio | One /media/process/ job per file | 1 file, 1 credit |
Batch conversions
Each item takes the same fields as POST /jobs/: url or sourceKey, filename, format and optionally inputFormat. The batch is validated as a whole — the response names the index of the first bad item — and every item becomes its own job.
curl -X POST 'https://maxscanner.app/api/v1/jobs/batch/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "jobs": [
{ "url": "https://example.com/a.docx", "filename": "a.docx", "format": "pdf" },
{ "url": "https://example.com/b.xlsx", "filename": "b.xlsx", "format": "pdf" }
] }'
curl 'https://maxscanner.app/api/v1/jobs/batch/$BATCH_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"Bulk workflow runs
Import or upload the files first (each import returns a documentId), then start one run per document in a single call. Runs are queued and processed in order on shared workers, so 100 Office files take minutes, not seconds; poll GET /api/v1/automations/{automationId}/runs/ every 15–30 seconds and read the counts per status.
import os, requests
KEY = os.environ["MAXSCANNER_API_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
BASE = "https://maxscanner.app/api/v1"
doc_ids = [requests.post(f"{BASE}/documents/import/", headers=H, json={"url": u, "filename": u.rsplit("/", 1)[-1]}, timeout=60).json()["documentId"] for u in urls]
r = requests.post(f"{BASE}/automations/{automation_id}/runs/", headers={**H, "Idempotency-Key": "invoices-2026-11"},
json={"mode": "each", "inputs": [{"kind": "document", "documentId": d} for d in doc_ids]}, timeout=60)
print(r.status_code, r.json().get("notStarted"))Retry safely
- Repeat a bulk run call with the same Idempotency-Key: runs that already exist are skipped (replayedCount) and only missing ones start
- If notStarted is present, the plan limit stopped the call; add credits or wait for the reset, then repeat the same request
- A failed run does not affect the others; start a new run for that document with a new Idempotency-Key
- Keep at most a few hundred runs in flight; wait for counts.completed to rise before sending the next hundred
Frequently asked questions
Is there a limit on how many runs can be queued?
Each call starts at most 100 runs. There is no separate queue cap, but runs share workers with other customers, so very large backlogs finish more slowly. Send work in batches of a few hundred.
Can I get one ZIP of all results?
Not from the API yet. Download each output from its document, or use the ZIP tools on the website.