---
title: "Run a batch"
method: POST
path: "/v1/tools/pdf_run_batch"
tags: ["Tools"]
---

# Run a batch

`POST /v1/tools/pdf_run_batch`

## Request

- Base URL: `http://127.0.0.1:7341`
- URL: `http://127.0.0.1:7341/v1/tools/pdf_run_batch`
- Auth: HTTP bearer

Apply the same 1–10 pipeline steps to each of 1–50 PDFs, one file at a time. Each result is written to output_folder as <name>-<suffix>.pdf. A file that fails is skipped and listed in failed with the reason; the rest continue.

Same tool as the MCP server's pdf_run_batch. Runs before responding; for long work, POST /v1/jobs instead.

## Request body

- PdfRunBatchInput
  - `inputs` string[], required: PDF paths to process.
  - `steps` PipelineStep[], required: Steps run in order, such as [{"action":"rotate","options":{"pages":"1","angle":90}}].
    - union
      - object
        - `action` 'extract', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - object
        - `action` 'remove', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
      - object
        - `action` 'rotate', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `angle` union: Clockwise rotation in degrees.
            - 90
            - 180
            - 270
      - object
        - `action` 'crop', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `margin` number: Points trimmed from each edge.
      - object
        - `action` 'scale', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `factor` number: Scale factor, 0.1–4.
      - object
        - `action` 'flatten', required
        - `options` object: Options as in the matching tool.
      - object
        - `action` 'labels', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `text` string
          - `position` 'top' | 'bottom'
      - object
        - `action` 'watermark', required
        - `options` object: Options as in the matching tool.
          - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
          - `text` string, required
      - object
        - `action` 'metadata-clear', required
        - `options` object: Options as in the matching tool.
  - `output_folder` string, required: Folder for the new files, inside an allowed folder; created if missing.
  - `suffix` string: Added to each output file name.

## Response `200`

The result. Any new files are written inside the allowed folders.

- PdfRunBatchResult
  - `outputs` object[], required
    - `output` string, required
    - `pages` integer, required
    - `bytes` integer, required
    - `input` string, required
  - `failed` object[], required
    - `input` string, required
    - `error` string, required

## Other responses

- `400`: The body is not valid JSON.
- `401`: The bearer token is missing or wrong.
- `403`: The Host or Origin header is not allowed.
- `409`: The output file already exists. superPDF never overwrites; choose a new name.
- `413`: The body is larger than 1 MB.
- `415`: The body is not application/json.
- `422`: Invalid input (errors names each field), a path outside the allowed folders, or a document the tool could not process.
- `429`: Too many tool calls are running and waiting (4 at once, 2 of them LibreOffice conversions; 64 more wait their turn).
- `500`: Unexpected server failure.

---

[API](https://skmtc.dev/superpdf/apis/superpdf-local-api.md) · [All operations](https://skmtc.dev/superpdf/apis/superpdf-local-api/llms.txt) · [OpenAPI document](https://skmtc.dev/superpdf/apis/superpdf-local-api/revisions/53f71d44b156?raw)