> ## Documentation Index > Fetch the complete documentation index at: https://docs.runpulse.com/llms.txt > Use this file to discover all available pages before exploring further. # Run Batch > Parse up to 1,000 documents with one config. Send them as `files`, as `file_urls`, or as a public `folder_url` in Amazon S3, Google Cloud Storage or Azure Blob Storage. Each document becomes its own `/parse` job, checked against your plan and billed when it runs. A job that fails doesn't stop the others. Uploaded or listed files of an unsupported type are skipped. A batch always runs async. Read its status at `GET /parse/batch/{batch_id}` and its manifest at `GET /parse/batch/{batch_id}/result`. A batch that isn't done in 48 hours fails. ## OpenAPI ````yaml /api-reference/v2/openapi.yml post /parse/batch openapi: 3.1.0 info: title: Pulse API description: >- Agentic document infrastructure for the enterprise. The Pulse API turns complex documents into AI-ready data, such as Markdown, structured JSON and bounding boxes. version: '2' servers: - url: https://api.runpulse.com description: Default Pulse API base URL security: [] tags: - name: Parse description: Parse a document's text, tables and figures. - name: Batch parse description: Parse many documents with one config. - name: Extract description: Extract structured data from a parsed document. - name: Split description: Find each topic's pages in a parsed document. - name: Tables description: Merge a parsed document's tables across pages. - name: Charts description: Read the charts in a parsed document. - name: Classify description: Sort a document into the categories you define. - name: Pipeline description: Run a parse and its follow-on steps as one job. - name: Usage description: Check the pages and credits your organization has used. - name: Webhook description: Get notified when your organization's jobs change status. - name: Organization settings description: Read and change your organization's name, address and default API version. paths: /parse/batch: post: tags: - Batch parse summary: Run Batch description: >- Parse up to 1,000 documents with one config. Send them as `files`, as `file_urls`, or as a public `folder_url` in Amazon S3, Google Cloud Storage or Azure Blob Storage. Each document becomes its own `/parse` job, checked against your plan and billed when it runs. A job that fails doesn't stop the others. Uploaded or listed files of an unsupported type are skipped. A batch always runs async. Read its status at `GET /parse/batch/{batch_id}` and its manifest at `GET /parse/batch/{batch_id}/result`. A batch that isn't done in 48 hours fails. operationId: parseBatch parameters: - name: Pulse-Version in: header required: false schema: type: string default: '2' title: Pulse-Version examples: default: value: '2' requestBody: required: true content: application/json: schema: description: A batch of documents to parse, all with one config. title: ParseBatchRequest oneOf: - title: File URLs, inline config additionalProperties: false type: object properties: file_urls: description: >- Public `http` or `https` URLs, or `s3://` or `gs://` URLs of public objects or of your organization's Pulse files. Each is fetched when its job runs, so a signed URL must still be valid then. items: minLength: 1 type: string maxItems: 1000 minItems: 1 title: File Urls type: array config: $ref: '#/components/schemas/ParseConfig' description: This request's options. required: - file_urls - config - title: File URLs, saved config additionalProperties: false type: object properties: file_urls: description: >- Public `http` or `https` URLs, or `s3://` or `gs://` URLs of public objects or of your organization's Pulse files. Each is fetched when its job runs, so a signed URL must still be valid then. items: minLength: 1 type: string maxItems: 1000 minItems: 1 title: File Urls type: array config_id: description: A saved config's id, sent in place of `config`. title: Config Id type: string required: - file_urls - config_id - title: Folder, inline config additionalProperties: false type: object properties: folder_url: description: >- A folder anyone can list and read, as `s3:////`, `gs:////`, `https://.blob.core.windows.net///` or the bucket's `https` URL. Hidden and archived files are skipped. It can hold at most 1,000 supported files and 10,000 objects. minLength: 1 title: Folder Url type: string max_depth: description: >- How many levels of subfolders to include. `0` takes only the folder's own files. Defaults to every level. minimum: 0 title: Max Depth type: integer config: $ref: '#/components/schemas/ParseConfig' description: This request's options. required: - folder_url - config - title: Folder, saved config additionalProperties: false type: object properties: folder_url: description: >- A folder anyone can list and read, as `s3:////`, `gs:////`, `https://.blob.core.windows.net///` or the bucket's `https` URL. Hidden and archived files are skipped. It can hold at most 1,000 supported files and 10,000 objects. minLength: 1 title: Folder Url type: string max_depth: description: >- How many levels of subfolders to include. `0` takes only the folder's own files. Defaults to every level. minimum: 0 title: Max Depth type: integer config_id: description: A saved config's id, sent in place of `config`. title: Config Id type: string required: - folder_url - config_id multipart/form-data: schema: oneOf: - title: Inline config type: object properties: files: type: array items: type: string format: binary maxItems: 1000 description: >- The documents to parse, as `multipart/form-data` file parts, each named `files`. Files without a supported extension (`.pdf`, `.jpg`, `.jpeg`, `.png`, `.tif`, `.tiff`, `.docx`, `.pptx`, `.xlsx`, `.xlsm`, `.xls`, `.html`, `.htm`) and hidden files are skipped. config: $ref: '#/components/schemas/ParseConfig' description: This request's options. required: - files - config - title: Saved config type: object properties: files: type: array items: type: string format: binary maxItems: 1000 description: >- The documents to parse, as `multipart/form-data` file parts, each named `files`. Files without a supported extension (`.pdf`, `.jpg`, `.jpeg`, `.png`, `.tif`, `.tiff`, `.docx`, `.pptx`, `.xlsx`, `.xlsm`, `.xls`, `.html`, `.htm`) and hidden files are skipped. config_id: description: A saved config's id, sent in place of `config`. title: Config Id type: string required: - files - config_id encoding: config: contentType: application/json responses: '202': description: >- The batch was accepted. The response holds its `batch_id` and when it was created. content: application/json: schema: $ref: '#/components/schemas/ParseBatchResponse' '400': description: >- The request is invalid ([`REQUEST_INVALID`](https://docs.runpulse.com/errors/request-invalid); `errors` names each problem). For example: the body isn't a JSON object or a multipart form; not exactly one of `files`, `file_urls` and `folder_url` was sent; `max_depth` came without `folder_url`; `config` and `config_id` were both sent, or neither; a config option is invalid; more than 1000 `files` or `file_urls` were sent; or no supported file was found. `folder_url` is also refused when it isn't a supported folder URL (a control character or a backslash in its path included), points at Pulse's own storage, names an S3 region that doesn't exist, can't be reached from this deployment, names a storage account that doesn't exist, can't be listed publicly or doesn't exist, or has more than 1000 supported files or more than 10,000 objects; or when the first non-empty file it lists can't be read publicly or is encrypted with a KMS key (Pulse checks that one file when you send the batch; any other file that can't be read fails its own job, which says why). On a self-hosted deployment, it's refused when it isn't a folder in the deployment's own storage under your organization's namespace. `Pulse-Version` names a version this API doesn't serve ([`UNSUPPORTED_VERSION`](https://docs.runpulse.com/errors/unsupported-version)). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' application/json: schema: $ref: '#/components/schemas/Problem' headers: X-Request-Id: description: The request's id; the problem's `request_id`. schema: type: string x-pulse-errors: - REQUEST_INVALID - UNSUPPORTED_VERSION '401': description: >- No API key was sent, or it isn't valid ([`CREDENTIALS_INVALID`](https://docs.runpulse.com/errors/credentials-invalid)), or it's inactive and needs replacing with a new key ([`API_KEY_INACTIVE`](https://docs.runpulse.com/errors/api-key-inactive)). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' application/json: schema: $ref: '#/components/schemas/Problem' headers: X-Request-Id: description: The request's id; the problem's `request_id`. schema: type: string x-pulse-errors: - CREDENTIALS_INVALID - API_KEY_INACTIVE '402': description: >- Your plan doesn't allow turning storage off: `config.storage.save` is `false` ([`PLAN_UPGRADE_REQUIRED`](https://docs.runpulse.com/errors/plan-upgrade-required)). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' application/json: schema: $ref: '#/components/schemas/Problem' headers: X-Request-Id: description: The request's id; the problem's `request_id`. schema: type: string x-pulse-errors: - PLAN_UPGRADE_REQUIRED '403': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' application/json: schema: $ref: '#/components/schemas/Problem' description: >- Your account is suspended ([`ACCOUNT_SUSPENDED`](https://docs.runpulse.com/errors/account-suspended)). headers: X-Request-Id: description: The request's id; the problem's `request_id`. schema: type: string x-pulse-errors: - ACCOUNT_SUSPENDED '404': description: >- `config_id` names no saved parse config ([`RESOURCE_NOT_FOUND`](https://docs.runpulse.com/errors/resource-not-found); `errors` names the field). No endpoint answers this path ([`ROUTE_NOT_FOUND`](https://docs.runpulse.com/errors/route-not-found)). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' application/json: schema: $ref: '#/components/schemas/Problem' headers: X-Request-Id: description: The request's id; the problem's `request_id`. schema: type: string x-pulse-errors: - RESOURCE_NOT_FOUND - ROUTE_NOT_FOUND '413': description: >- A text part of the multipart form, such as `config` or `file_urls`, is over 10 MB ([`FIELD_TOO_LARGE`](https://docs.runpulse.com/errors/field-too-large)). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' application/json: schema: $ref: '#/components/schemas/Problem' headers: X-Request-Id: description: The request's id; the problem's `request_id`. schema: type: string x-pulse-errors: - FIELD_TOO_LARGE '500': description: >- An unexpected error occurred ([`SERVER_ERROR`](https://docs.runpulse.com/errors/server-error)). Retry the request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' application/json: schema: $ref: '#/components/schemas/Problem' headers: X-Request-Id: description: The request's id; the problem's `request_id`. schema: type: string x-pulse-errors: - SERVER_ERROR '503': description: >- The batch wasn't started ([`SERVICE_UNAVAILABLE`](https://docs.runpulse.com/errors/service-unavailable); `detail` says why): `folder_url` couldn't be listed within 45 seconds, or its storage answered with an error, throttled the listing or didn't answer; or a service the batch needs was unavailable. A retry can fix these. Or document processing is at capacity ([`CAPACITY_EXCEEDED`](https://docs.runpulse.com/errors/capacity-exceeded)); the batch wasn't started: retry after `Retry-After` seconds. On a self-hosted deployment, [`LICENSE_NOT_ACTIVATED`](https://docs.runpulse.com/errors/license-not-activated) until the deployment is activated, and [`LICENSE_INVALID`](https://docs.runpulse.com/errors/license-invalid) when its license is invalid or expired. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' application/json: schema: $ref: '#/components/schemas/Problem' headers: X-Request-Id: description: The request's id; the problem's `request_id`. schema: type: string Retry-After: description: Seconds to wait before retrying. schema: type: string x-pulse-errors: - SERVICE_UNAVAILABLE - CAPACITY_EXCEEDED - LICENSE_NOT_ACTIVATED - LICENSE_INVALID security: - ApiKey: [] components: schemas: ParseConfig: additionalProperties: false description: The options for a parse. properties: model: description: The model to parse with. enum: - ultra-2 title: Model type: string storage: $ref: '#/components/schemas/Storage' description: Whether the result is saved, and where. page_range: description: >- The pages to parse, listed as numbers and ranges from 1, such as `1-3, 6, 8-end` (`end` is the last page). Defaults to every page. A spreadsheet's pages are its sheets, hidden ones included. pattern: ^ *[0-9]+ *(- *([0-9]+|end) *)?(, *[0-9]+ *(- *([0-9]+|end) *)?)*$ title: Page Range type: string prompt: description: Extra instructions for reading the document, added to Pulse's own. minLength: 1 title: Prompt type: string extensions: $ref: '#/components/schemas/Extensions' default: additional_formats: [] footnotes: false document_metadata: false word_level_bounding_boxes: false chunking: strategies: [] description: Extra outputs to add to the result. enhancements: $ref: '#/components/schemas/Enhancements' default: detect: [] figures: describe: [] include: false prompt: null refine: modes: [] spreadsheet: cell_formatting: false include_hidden: [] raw_values: false trim_empty: [] required: - model title: ParseConfig { model, storage, page_range, 3 more } type: object ParseBatchResponse: properties: batch_id: type: string title: Batch Id description: The batch's id, `batch-`. created_at: type: string title: Created At description: When the batch was accepted. additionalProperties: false type: object required: - batch_id - created_at title: ParseBatchResponse description: A batch that was accepted for parsing. Problem: additionalProperties: false description: >- Why the request or the job failed. Branch on `code`; quote `request_id` to support. properties: type: description: 'This code''s page: what it means and what to do.' title: Type type: string title: description: A short summary of the code, the same for every occurrence. title: Title type: string status: description: The HTTP status the code answers with. title: Status type: integer detail: description: What happened this time. title: Detail type: string instance: description: 'This occurrence: the request''s URN, `urn:pulse:request:`.' title: Instance type: string code: description: The stable error code, e.g. `REQUEST_INVALID`. Branch on it. title: Code type: string request_id: description: >- The request that failed, as `X-Request-Id` named it; for a failed job, the request that created it. Quote it to support. title: Request Id type: string retryable: description: Whether the same request may succeed if sent again. title: Retryable type: boolean retry_after: description: Seconds to wait before retrying, as `Retry-After` says. title: Retry After type: integer errors: description: Each refused part of the request. items: $ref: '#/components/schemas/FieldIssue' title: Errors type: array resource: description: 'What wasn''t found: `job`, `batch`, `webhook`, `config`, …' title: Resource type: string reason: description: The cause within the code. title: Reason type: string parse_id: description: The parse the request recorded. title: Parse Id type: string extract_id: description: The extraction it recorded. title: Extract Id type: string split_id: description: The split it recorded. title: Split Id type: string classify_id: description: The classification it recorded. title: Classify Id type: string tables_id: description: The tables job it recorded. title: Tables Id type: string charts_id: description: The charts job it recorded. title: Charts Id type: string pipeline_id: description: The pipeline it recorded. title: Pipeline Id type: string batch_id: description: The batch it recorded. title: Batch Id type: string filename: description: The file refused. title: Filename type: string declared_type: description: The type its name declared. title: Declared Type type: string detected: description: The type its contents are. title: Detected type: string supported_types: description: The types accepted. items: type: string title: Supported Types type: array supported: description: The values accepted. items: type: string title: Supported type: array max_size_mb: anyOf: - type: integer - type: number description: The largest size accepted. title: Max Size Mb file_size_mb: anyOf: - type: integer - type: number description: The file's size. title: File Size Mb plan_name: description: Your organization's plan. title: Plan Name type: string pages_used: anyOf: - type: integer - type: number description: Pages used this period. title: Pages Used page_allowance: anyOf: - type: integer - type: number description: Pages the plan allows. title: Page Allowance upgrade_url: description: Where to change your plan. title: Upgrade Url type: string action_required: description: What to do to continue. title: Action Required type: string billing_info: additionalProperties: $ref: '#/components/schemas/JsonValue' description: Your organization's billing state, as the gate read it. title: Billing Info type: object required: - type - title - status - code - retryable title: Problem type: object Storage: additionalProperties: false description: >- Whether the result is saved to your organization's Pulse dashboard, and in which folder. properties: save: description: >- `true` saves the result, and `false` keeps it only until `expires_at`, 24 hours by default. If omitted, it's saved unless your organization turned saving off, which also overrides `true`. Free plans can't send `false`. title: Save type: boolean folder_id: description: >- The dashboard folder to save the result in. Sending it saves the result, so it's refused with `save: false`. Another organization's folder is ignored. minLength: 1 title: Folder Id type: string title: Storage { save, folder_id } type: object Extensions: additionalProperties: false description: >- Extra outputs to add to the result, each under the result's `extensions`. properties: additional_formats: default: [] description: >- Other formats to return the document in, under `extensions.additional_formats`. Choose from `html` (the Markdown as HTML), `xml` (the elements, by page) and `tagged_md` (the Markdown with element ids). items: enum: - html - xml - tagged_md type: string title: Additional Formats type: array footnotes: default: false description: >- Set to `true` to find the document's footnotes and link each one to the elements that cite it, in `extensions.footnotes`. title: Footnotes type: boolean document_metadata: default: false description: >- Set to `true` to return the metadata the file carries, such as its title, authors or a PDF's form fields, in `extensions.document_metadata`. title: Document Metadata type: boolean word_level_bounding_boxes: default: false description: >- Set to `true` to return every word with its outline, as `Word` elements in `extensions.word_level_bounding_boxes`. This option must be enabled for your organization. title: Word Level Bounding Boxes type: boolean chunking: $ref: '#/components/schemas/Chunking' default: strategies: [] title: Extensions { additional_formats, footnotes, document_metadata, 2 more } type: object Enhancements: additionalProperties: false description: Optional passes that add to the parse or correct it. properties: detect: default: [] description: >- Send `["selections"]` to detect checkboxes, radio buttons and similar controls, and mark each ticked one `selected: true`. items: const: selections type: string title: Detect type: array figures: $ref: '#/components/schemas/Figures' default: describe: [] include: false prompt: null description: Descriptions and images of the document's figures. refine: $ref: '#/components/schemas/Refine' default: modes: [] description: Passes that correct the parse. spreadsheet: $ref: '#/components/schemas/Spreadsheet' default: include_hidden: [] trim_empty: [] raw_values: false cell_formatting: false description: Options for spreadsheets. title: Enhancements { detect, figures, refine, 1 more } type: object FieldIssue: additionalProperties: false description: One refused part of the request. properties: field: description: >- The part as sent: a body field's path (`config.enhancements.detect[1]`), or `query.` / `header.`. title: Field type: string pointer: description: >- A body field as a JSON Pointer (RFC 6901), e.g. `#/config/enhancements/detect/1`. Absent for a query parameter or header. title: Pointer type: string issue: description: What is wrong with it. title: Issue type: string required: - field - issue title: FieldIssue type: object JsonValue: {} Chunking: additionalProperties: false properties: strategies: default: [] items: $ref: '#/components/schemas/SemanticStrategy' title: Strategies type: array title: Chunking type: object Figures: additionalProperties: false description: >- What to return for the document's figures: its charts, diagrams, photos and other pictures. properties: describe: default: [] description: >- Send `["all"]` to describe every figure in its `description`. A figure that can't be described gets none, with a `FIGURE_DESCRIPTIONS_SKIPPED` warning on the result. items: const: all type: string title: Describe type: array include: default: false description: >- Set to `true` to return each figure's image, base64-encoded, in its `figure_base64`. title: Include type: boolean prompt: description: >- Extra instructions for the figure descriptions. Used only with `describe`. minLength: 1 title: Prompt type: string title: Figures { describe, include, prompt } type: object Refine: additionalProperties: false description: Passes that check the parse against the page images and correct it. properties: modes: default: [] description: >- The passes to run, each mode at most once. A page they can't correct is returned as parsed, with a `REFINE_SKIPPED` warning on the result. items: $ref: '#/components/schemas/RefineMode' title: Modes type: array title: Refine type: object Spreadsheet: additionalProperties: false description: Options for spreadsheets. Other documents ignore them. properties: include_hidden: default: [] description: >- The hidden `rows`, `columns` or `sheets` to read. By default, hidden parts are skipped. items: enum: - rows - columns - sheets type: string title: Include Hidden type: array trim_empty: default: [] description: >- Send `rows`, `columns` or both to drop empty but formatted ones past a sheet's last value. Some exported workbooks carry thousands of them. Kept cells keep their addresses. Applies to `.xlsx` and `.xlsm` files only. items: enum: - rows - columns type: string title: Trim Empty type: array raw_values: default: false description: >- Set to `true` to add each cell's underlying value as its `raw_value`, such as `1201.67` where `content` shows `$1,202`. title: Raw Values type: boolean cell_formatting: default: false description: >- Set to `true` to add each cell's formatting (font, fill, borders and alignment) as its `style`. title: Cell Formatting type: boolean title: Spreadsheet { include_hidden, trim_empty, raw_values, 1 more } type: object SemanticStrategy: additionalProperties: false description: >- Chunks cut where the meaning of neighboring sentences drifts apart. A chunk longer than `max_characters` is cut again. Without `max_characters`, chunk length has no cap. properties: strategy: const: semantic title: Strategy type: string max_characters: maximum: 100000 minimum: 20 title: Max Characters type: integer required: - strategy title: SemanticStrategy { strategy, max_characters } type: object RefineMode: additionalProperties: false description: >- One pass that checks the parsed content against the page images and corrects it. properties: mode: description: >- `tables` fixes cells and structure. `formatting` fixes bold, headings, lists and math, not words. `text` fixes misread words and numbers, not formatting. `layout` fixes a figure or table read as the wrong kind. enum: - tables - formatting - text - layout title: Mode type: string prompt: description: >- Extra instructions for this pass. A prompt sent with `layout` is refused (`REQUEST_INVALID`). minLength: 1 title: Prompt type: string required: - mode title: RefineMode { mode, prompt } type: object securitySchemes: ApiKey: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.