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

# Get Batch PDF Status

> Retrieve the status of a batch PDF generation request using the batchRequestId.

<Note>
  Use this endpoint to check the status of a batch PDF generation request. This is useful when:

  <ul>
    <li>You've sent a batch request with `async: true` and want to poll for progress</li>
    <li>A synchronous batch request timed out (>30 seconds) and you need to check on its progress</li>
  </ul>

  If you want to check the status of a single PDF generation (not a batch), use the [Get PDF Status](/api-reference/pdf-status/get) endpoint instead.
</Note>

GET [https://api.pdfnoodle.com/v1/pdf/batch/status/:batchRequestId](https://api.pdfnoodle.com/v1/pdf/batch/status/:batchRequestId)

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789' \
  --header 'Authorization: Bearer pdfnoodle_api_123456789'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789",
    {
      method: "GET",
      headers: {
        Authorization: "Bearer pdfnoodle_api_123456789",
      },
    }
  );

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789',
      headers={
          'Authorization': 'Bearer pdfnoodle_api_123456789'
      }
  )

  result = response.json()
  ```
</CodeGroup>

## Response

The endpoint responds with `200 OK` and returns the current status of the batch PDF generation:

<CodeGroup>
  ```json ONGOING theme={null}
  {
    "batchRequestId": "pdfnoodle_batch_123456789",
    "status": "ONGOING",
    "total": 3,
    "completed": 1,
    "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": "ONGOING",
        "signedUrl": "",
        "metadata": {}
      },
      {
        "requestId": "pdfnoodle_request_ghi789",
        "renderStatus": "ONGOING",
        "signedUrl": "",
        "metadata": {}
      }
    ]
  }
  ```

  ```json SUCCESS 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 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 FAILED theme={null}
  {
    "batchRequestId": "pdfnoodle_batch_123456789",
    "status": "FAILED",
    "total": 2,
    "completed": 2,
    "merge": false,
    "results": [
      {
        "requestId": "pdfnoodle_request_abc123",
        "renderStatus": "FAILED",
        "signedUrl": "",
        "metadata": {}
      },
      {
        "requestId": "pdfnoodle_request_def456",
        "renderStatus": "FAILED",
        "signedUrl": "",
        "metadata": {}
      }
    ]
  }
  ```
</CodeGroup>

## Parameters

<ParamField path="batchRequestId" type="string" required>
  The batchRequestId returned from a batch PDF generation request
</ParamField>

## Response Fields

<ParamField response="batchRequestId" type="string">
  The unique identifier for this batch PDF generation request
</ParamField>

<ParamField response="status" type="string">
  The current status of the batch. Possible values:

  * `ONGOING` - PDFs are still being generated
  * `SUCCESS` - All PDFs have been successfully generated
  * `PARTIAL_SUCCESS` - Some PDFs were generated, but at least one failed
  * `FAILED` - All PDFs failed to generate
</ParamField>

<ParamField response="total" type="number">
  The total number of PDFs in the batch
</ParamField>

<ParamField response="completed" type="number">
  The number of PDFs that have finished processing (either succeeded or failed)
</ParamField>

<ParamField response="merge" type="boolean">
  Whether the batch was requested with merge enabled
</ParamField>

<ParamField response="mergedUrl" type="string">
  A temporary URL pointing to the merged PDF file. Only present when `merge` is `true`
  and at least one PDF was generated successfully. The URL expires after the time
  specified in `signedUrlExpiresIn`.
</ParamField>

<ParamField response="results" type="array">
  An array of individual PDF results. Each result contains:

  * **requestId** - Unique identifier for the individual PDF request
  * **renderStatus** - `ONGOING`, `SUCCESS`, or `FAILED`
  * **signedUrl** - Temporary URL to the generated PDF (empty when `ONGOING` or `FAILED`)
  * **metadata** - Contains `executionTime` and `fileSize` on `SUCCESS`
</ParamField>

<Danger>
  If any individual PDF has `renderStatus` of `FAILED`, you should contact support
  to figure out why the PDF generation failed.
</Danger>

## Usage Example

Here's a complete example of polling for batch PDF status:

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    async function checkBatchStatus(batchRequestId) {
      const maxAttempts = 60; // Poll for up to 5 minutes (60 * 5 seconds)
      let attempts = 0;

      while (attempts < maxAttempts) {
        const response = await fetch(
          `https://api.pdfnoodle.com/v1/pdf/batch/status/${batchRequestId}`,
          {
            method: "GET",
            headers: {
              Authorization: "Bearer pdfnoodle_api_123456789",
            },
          }
        );

        const result = await response.json();

        if (result.status === "SUCCESS" || result.status === "PARTIAL_SUCCESS") {
          return result;
        }

        if (result.status === "FAILED") {
          throw new Error("All PDFs in the batch failed to generate");
        }

        // Wait 5 seconds before checking again
        await new Promise((resolve) => setTimeout(resolve, 5000));
        attempts++;
      }

      throw new Error("Batch PDF generation timed out");
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import time

    def check_batch_status(batch_request_id):
        max_attempts = 60  # Poll for up to 5 minutes (60 * 5 seconds)
        attempts = 0

        while attempts < max_attempts:
            response = requests.get(
                f'https://api.pdfnoodle.com/v1/pdf/batch/status/{batch_request_id}',
                headers={
                    'Authorization': 'Bearer pdfnoodle_api_123456789'
                }
            )

            result = response.json()

            if result['status'] in ['SUCCESS', 'PARTIAL_SUCCESS']:
                return result

            if result['status'] == 'FAILED':
                raise Exception('All PDFs in the batch failed to generate')

            # Wait 5 seconds before checking again
            time.sleep(5)
            attempts += 1

        raise Exception('Batch PDF generation timed out')
    ```
  </Tab>
</Tabs>

## Checking Individual PDF Status

If you want to check on the status of a specific PDF within the batch, you can use the [Get PDF Status](/api-reference/pdf-status/get) endpoint with the individual `requestId` from the `results` array.