> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pdfnoodle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Batch Request
> Convert multiple HTML documents to PDFs in a single request. Process up to 20 PDFs at once, with optional merging into a single file.
Batch HTML to PDF allows you to convert up to 20 HTML documents into PDFs in a single API call.
You can also merge all generated PDFs into a single file.
POST [https://api.pdfnoodle.com/v1/html-to-pdf/batch](https://api.pdfnoodle.com/v1/html-to-pdf/batch)
## Request
```bash cURL theme={null}
curl --location 'https://api.pdfnoodle.com/v1/html-to-pdf/batch' \
--header 'Authorization: Bearer pdfnoodle_api_123456789' \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"html": "Invoice #001
Total: $150.00
"
},
{
"html": "Invoice #002
Total: $250.00
"
}
],
"merge": false
}'
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.pdfnoodle.com/v1/html-to-pdf/batch", {
method: "POST",
headers: {
Authorization: "Bearer pdfnoodle_api_123456789",
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [
{
html: "Invoice #001
Total: $150.00
",
},
{
html: "Invoice #002
Total: $250.00
",
},
],
merge: false,
}),
});
const result = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.pdfnoodle.com/v1/html-to-pdf/batch',
headers={
'Authorization': 'Bearer pdfnoodle_api_123456789',
'Content-Type': 'application/json'
},
json={
'items': [
{
'html': 'Invoice #001
Total: $150.00
'
},
{
'html': 'Invoice #002
Total: $250.00
'
}
],
'merge': False
}
)
result = response.json()
```
## Response
By default, the request waits for all PDFs to be generated before returning a response (synchronous behavior). If the batch takes longer than 30 seconds, it will return a `202 Accepted` response with a status URL to poll.
```json Success (200 OK) theme={null}
{
"batchRequestId": "pdfnoodle_batch_123456789",
"status": "SUCCESS",
"total": 2,
"completed": 2,
"merge": false,
"results": [
{
"requestId": "pdfnoodle_request_abc123",
"renderStatus": "SUCCESS",
"signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
"metadata": {
"executionTime": "1.805 seconds",
"fileSize": "4.066 kB"
}
},
{
"requestId": "pdfnoodle_request_def456",
"renderStatus": "SUCCESS",
"signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
"metadata": {
"executionTime": "2.103 seconds",
"fileSize": "5.200 kB"
}
}
]
}
```
```json Partial Success (200 OK) theme={null}
{
"batchRequestId": "pdfnoodle_batch_123456789",
"status": "PARTIAL_SUCCESS",
"total": 2,
"completed": 2,
"merge": false,
"results": [
{
"requestId": "pdfnoodle_request_abc123",
"renderStatus": "SUCCESS",
"signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
"metadata": {
"executionTime": "1.805 seconds",
"fileSize": "4.066 kB"
}
},
{
"requestId": "pdfnoodle_request_def456",
"renderStatus": "FAILED",
"signedUrl": "",
"metadata": {}
}
]
}
```
```json Timeout (202 Accepted) theme={null}
{
"batchRequestId": "pdfnoodle_batch_123456789",
"statusUrl": "https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789",
"message": "Batch couldn't complete within 30 seconds. Check the batch status URL for progress."
}
```
The `status` field indicates the overall outcome of the batch:
* **SUCCESS** - All PDFs were generated successfully
* **PARTIAL\_SUCCESS** - Some PDFs were generated, but at least one failed
* **FAILED** - All PDFs failed to generate
### Merged Response
When `merge` is set to `true`, the response will also include a `mergedUrl` pointing to a single PDF containing all successfully generated PDFs combined:
```json theme={null}
{
"batchRequestId": "pdfnoodle_batch_123456789",
"status": "SUCCESS",
"total": 2,
"completed": 2,
"merge": true,
"mergedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/merged/...",
"results": [...]
}
```
## Parameters
An array of HTML to PDF conversion items. Minimum 1 item, maximum 20 items per batch.
Each item accepts the following properties:
The HTML content you want to render
The object containing the parameters for your PDF. [See all the options
here](/api-reference/options/pdf-params).
If true, will return a .PNG file instead of a .PDF file
The id of the active s3 connection you want to store your generated file on.
(only available in the high plan)
The path, including subdirectories and the filename without extension, to use
when saving the render in your S3 bucket. (only available if being stored in
custom s3\_bucket)
This object containing the metadata for your PDF. [See all the options
here](/api-reference/options/pdf-metadata).
If true, will hide the footer and the header elements on the first page of the
generated PDF
If true, will enter Debug Mode and show additional properties on the response
to help you figure out your variables and html rendered content. [Here's
everything you need to know about Debug
Mode](/api-reference/options/debug-mode)
If true, the request will return immediately with a `batchRequestId` and
`statusUrl`. You can poll the [Get Batch PDF Status](/api-reference/pdf-status/get-batch)
endpoint to track progress.
If true, all successfully generated PDFs will be merged into a single file.
The merged file URL will be available in the `mergedUrl` field of the response.
Cannot be used when any item has `convertToImage` set to `true`.
A URL to receive a POST request when the batch is complete. The webhook payload
will contain the full batch status and results.
Number of seconds that the generated signed URLs will take to expire (default:
1 hour)
## Async Mode
When `async` is set to `true`, the request returns immediately with a `batchRequestId` and a `statusUrl`:
```json theme={null}
{
"batchRequestId": "pdfnoodle_batch_123456789",
"statusUrl": "https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789",
"total": 2,
"subRequestIds": ["pdfnoodle_request_abc123", "pdfnoodle_request_def456"],
"message": "Batch PDF generation started. Check the status URL for progress."
}
```
You can then check the status of your batch using the [Get Batch PDF Status](/api-reference/pdf-status/get-batch) endpoint.
## Payload Size Limit
The request body is limited to **3MB**. Since batch requests contain multiple items with raw HTML content, this limit can be reached quickly when sending many items with large HTML documents.
If your request exceeds this limit, you'll receive a `413` status code with the following error:
```json theme={null}
{
"message": "request entity too large"
}
```
If you're hitting the 3MB payload limit, consider splitting your batch into
multiple smaller requests. For example, instead of sending 20 items in a single
request, send two requests with 10 items each.
## Checking Batch Status
You can check the status of your batch at any time using the [Get Batch PDF Status](/api-reference/pdf-status/get-batch) endpoint with the `batchRequestId`.
To check the status of an individual PDF within the batch, use the [Get PDF Status](/api-reference/pdf-status/get) endpoint with the individual `requestId` from the results.