Get Tool Status

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

You’ve set async: true and want to poll for the result
A synchronous request timed out (>30 seconds) and was automatically processed in the background

GET https://api.pdfnoodle.com/v1/tools/status/:requestId

Request

curl --location 'https://api.pdfnoodle.com/v1/tools/status/pdfnoodle_request_123456789' \
--header 'Authorization: Bearer pdfnoodle_api_123456789'

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();

import requests

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

result = response.json()

Response

The endpoint responds with 200 OK and returns the current status of the tool operation:

{
  "requestId": "pdfnoodle_request_123456789",
  "status": "ONGOING",
  "result": null,
  "metadata": {}
}

{
  "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"
  }
}

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

{
  "message": "Couldn't find this request in queue"
}

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

string

required

The requestId returned from an async tool request or from a synchronous request that timed out.

Response Fields

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

Usage Example

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

Node.js
Python

// 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);

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'])

Getting Started

Generate PDF from Template

Convert HTML to PDF

PDFs

Templates

Options

Guides

Request

Response

Parameters

Response Fields

Usage Example

​Request

​Response

​Parameters

​Response Fields

​Usage Example

Request

Response

Parameters

Response Fields

Usage Example