The batch endpoint runs up to 50 files concurrently, returns per-file statuses, and creates a single billing entry. Here is when to reach for it.

Batch PDF processing lets you send up to 50 files in a single HTTP request, run them concurrently on the server, and receive one consolidated response with per-file statuses. On ASHDOCS, this is POST /api/v1/batch, and it matters because it eliminates the request overhead of firing 50 sequential calls, produces one entry in your credit ledger instead of 50, and — since retries are per-file — you never re-process a file that already succeeded.

When should I reach for the batch endpoint instead of individual calls?

What does a batch request look like?

Batch is one endpoint that dispatches to any of the 23 tools via tool_key. All files in a batch use the same tool and the same options payload — send heterogeneous files as separate batches.

curl -X POST https://www.ashdocs.com/api/v1/batch \
  -H "X-API-Key: ash_live_xxxxxxxx" \
  -F "tool_key=pdf-to-markdown" \
  -F "files=@a.pdf" \
  -F "files=@b.pdf" \
  -F "files=@c.pdf" \
  -F 'options={ "include_page_markers": false }' \
  -F "max_concurrency=8"

What does the response include?

{
  "batch_id": "batch_01H...",
  "tool_key": "pdf-to-markdown",
  "credits_consumed": 6,
  "results": [
    { "request_id": "req_a", "filename": "a.pdf", "status": "completed", "output_files": [ ... ] },
    { "request_id": "req_b", "filename": "b.pdf", "status": "completed", "output_files": [ ... ] },
    { "request_id": "req_c", "filename": "c.pdf", "status": "failed",    "error": "virus_detected" }
  ],
  "summary": { "total": 3, "completed": 2, "failed": 1 }
}

Every result includes a stable request_id so per-file retries land on the same ledger entry — you never double-charge a redo.

How does concurrency work?

Can I retrieve a batch's status later?

Yes. If your first call times out or you want to poll instead of waiting on the response, GET /api/v1/batch/{batch_id} returns the same shape at any time.

How much does a batch cost?

Batch pricing is per-file, not per-batch — a batch of 50 HTML-to-PDF files still costs 50 × 1 = 50 credits. The saving is on request overhead and on billing hygiene: one row in your credit ledger labelled batch/pdf-to-markdown × 3 is dramatically easier to audit than 50 separate rows.

Frequently asked questions

What is the max file size per file inside a batch?

The same 25 MB per-file limit that applies to single-file requests. The batch upload as a whole is capped at 500 MB. Files larger than 25 MB should use the chunked upload flow documented in /docs/data-extraction.

Can I mix tools in a single batch?

No. Every batch runs one tool_key against every file. If you need heterogeneous processing (e.g. redact then extract), chain two batches through a pipeline instead.

What happens if one file fails? Does the batch fail?

No. Each file has an independent status. Failed files land in results[] with a status: "failed" and an error code. Successful files still deliver via your webhook / destination as usual.

Are batch results streamable?

Not yet — the endpoint returns the full response once every file has finished (or the batch has timed out). Streaming per-file completions is on the roadmap; use webhooks in the meantime for per-file completion signals.

Batch PDF processing — 50 files per request, one credit ledger entry