Skip to main content

Find your next tool

Docs/API/Bulk document processing with the API
API

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.

JobUsePer 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 audioOne /media/process/ job per file1 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.

Related guides