---
title: "Batches"
description: "A batch is several files sent in one POST /v1/convert/{name} call. There is no separate batch endpoint."
url: https://markitdown.ai/docs/batches
updated: 2026-09-25
source: markitdown.ai
---

# Batches

> A batch is several files sent in one POST /v1/convert/{name} call. There is no separate batch endpoint.

## Submit many files at once

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.

**Three PDFs, one conversion**

```bash
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
```

## Track progress across files

`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.

## Which inputs can I combine in one request?

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 `file`s, 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`).

## What is checked before all the files run?

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.

## How do I collect the results?

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.

## Related

- [Convert](https://markitdown.ai/docs/convert)
- [Conversions](https://markitdown.ai/docs/conversions)
- [Conversion Files](https://markitdown.ai/docs/files)
- [Introduction](https://markitdown.ai/docs)
- [Document Conversion APIs](https://markitdown.ai/developers)