> ## 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 Tool Status

> Retrieve the status of a tool operation using the requestId returned when using async mode or when a synchronous request times out.

<Note>
  Use this endpoint to check the status of a tool operation. This is particularly useful when:

  <ul>
    <li>You've set `async: true` and want to poll for the result</li>
    <li>A synchronous request timed out (>30 seconds) and was automatically processed in the background</li>
  </ul>
</Note>

GET [https://api.pdfnoodle.com/v1/tools/status/:requestId](https://api.pdfnoodle.com/v1/tools/status/:requestId)

## Request

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

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.pdfnoodle.com/v1/tools/status/pdfnoodle_request_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/tools/status/pdfnoodle_request_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 tool operation:

<CodeGroup>
  ```json ONGOING theme={null}
  {
    "requestId": "pdfnoodle_request_123456789",
    "status": "ONGOING",
    "result": null,
    "metadata": {}
  }
  ```

  ```json SUCCESS theme={null}
  {
    "requestId": "pdfnoodle_request_123456789",
    "status": "SUCCESS",
    "result": {
      "url": "https://s3.amazonaws.com/...",
      "fileName": "merged-report.pdf",
      "urlValidUntil": "2025-01-01T02:00:00.000Z"
    },
    "metadata": {
      "toolName": "mergePdfs"
    }
  }
  ```

  ```json FAILED theme={null}
  {
    "requestId": "pdfnoodle_request_123456789",
    "status": "FAILED",
    "result": null,
    "metadata": {
      "errorMessage": "Error while merging PDFs",
      "toolName": "mergePdfs"
    }
  }
  ```

  ```json Not Found (404) theme={null}
  {
    "message": "Couldn't find this request in queue"
  }
  ```
</CodeGroup>

The `result` object contains the same response body you would receive from a synchronous tool request. For example, a merge operation returns `url`, `fileName`, and `urlValidUntil`, while a split operation returns `urls`, `totalParts`, etc.

## Parameters

<ParamField path="requestId" type="string" required>
  The requestId returned from an async tool request or from a synchronous
  request that timed out.
</ParamField>

## Response Fields

<ParamField response="requestId" type="string">
  The unique identifier for this tool operation request.
</ParamField>

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

  * `ONGOING` - The operation is still being processed
  * `SUCCESS` - The operation completed successfully
  * `FAILED` - The operation failed
</ParamField>

<ParamField response="result" type="object">
  The result of the tool operation. This will be `null` when `status` is
  `ONGOING` or `FAILED`. When `SUCCESS`, it contains the same fields as the
  synchronous response for the specific tool used.
</ParamField>

<ParamField response="metadata" type="object">
  Additional metadata about the operation. Contains:

  * **toolName** - The name of the tool that was executed (present on `SUCCESS` and `FAILED`)
  * **errorMessage** - Error description (only present when `status` is `FAILED`)
</ParamField>

<Danger>
  If the `status` is `FAILED`, check the `metadata.errorMessage` for details
  on what went wrong. Contact support if the issue persists.
</Danger>

## Usage Example

Here's a complete example of using async mode with polling:

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    // Step 1: Make an async tool request
    const response = await fetch("https://api.pdfnoodle.com/v1/tools/merge-pdfs", {
      method: "POST",
      headers: {
        Authorization: "Bearer pdfnoodle_api_123456789",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        urls: [
          "https://example.com/document-1.pdf",
          "https://example.com/document-2.pdf",
        ],
        async: true,
      }),
    });

    const { requestId, statusUrl } = await response.json();

    // Step 2: Poll for the result
    async function pollForResult(requestId) {
      const maxAttempts = 60;
      let attempts = 0;

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

        const result = await statusResponse.json();

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

        if (result.status === "FAILED") {
          throw new Error(result.metadata.errorMessage);
        }

        await new Promise((resolve) => setTimeout(resolve, 5000));
        attempts++;
      }

      throw new Error("Operation timed out");
    }

    const result = await pollForResult(requestId);
    console.log("Merged PDF URL:", result.url);
    ```
  </Tab>

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

    # Step 1: Make an async tool request
    response = requests.post(
        'https://api.pdfnoodle.com/v1/tools/merge-pdfs',
        headers={
            'Authorization': 'Bearer pdfnoodle_api_123456789',
            'Content-Type': 'application/json'
        },
        json={
            'urls': [
                'https://example.com/document-1.pdf',
                'https://example.com/document-2.pdf'
            ],
            'async': True
        }
    )

    data = response.json()
    request_id = data['requestId']

    # Step 2: Poll for the result
    def poll_for_result(request_id):
        max_attempts = 60
        attempts = 0

        while attempts < max_attempts:
            status_response = requests.get(
                f'https://api.pdfnoodle.com/v1/tools/status/{request_id}',
                headers={
                    'Authorization': 'Bearer pdfnoodle_api_123456789'
                }
            )

            result = status_response.json()

            if result['status'] == 'SUCCESS':
                return result['result']

            if result['status'] == 'FAILED':
                raise Exception(result['metadata']['errorMessage'])

            time.sleep(5)
            attempts += 1

        raise Exception('Operation timed out')

    result = poll_for_result(request_id)
    print('Merged PDF URL:', result['url'])
    ```
  </Tab>
</Tabs>