Batches

Repeat the multipart file field, or send a files array of file_… references, on the same POST /v1/convert/{name} call — up to 100 multipart files (100 MB total) or 1000 references. The response is one conversion with one entry per source file in files[]; there is no separate batch resource to create, poll, or delete.

curl -X POST https://api.markitdown.ai/v1/convert/pdf \
  -H "x-api-key: mdai_…" \
  -H "Idempotency-Key: 7d0e…" \
  -F file=@invoice-001.pdf \
  -F file=@invoice-002.pdf \
  -F file=@invoice-003.pdf

summary on the conversion reports how many source files are queued, running, completed, and failed; each entry in files[] (or a page of GET /v1/conversions/{id}/files) carries its own status, pages, credits, and error. Subscribe to GET /v1/conversions/{id}/events to watch the counts change live instead of polling the whole conversion repeatedly.

Only files of the same name — a /v1/convert/pdf call cannot also carry a .docx file, because the endpoint decides the accepted extensions. Send .docx files to /v1/convert/word as a separate call. Multipart files, JSON file/files references, and JSON text/texts can each repeat within their own kind, but a submission may not mix input kinds (415 input_format_mismatch).

The API sizes and inspects every source file before it creates anything. If one file exceeds your plan's page cap the whole request returns 422 page_cap_exceeded, and if the credits for every source together exceed your balance it returns 402 insufficient_credits, so an oversized or unaffordable submission is rejected before any file runs. Retrying with the same Idempotency-Key returns the existing conversion instead of creating it twice.

Read files[] on the conversion (or page GET /v1/conversions/{id}/files for more than 100), and each output's content when it is inlined. Match a source file back to your own record with client_metadata on the submission, or by the order you sent the files. One failed file does not stop the others; the conversion ends as completed_with_errors and only completed files are charged. A single conversion.completed or conversion.failed webhook fires once for the whole request, not once per file.