Poll for API Request Status with Python

Share this page

Learn how to submit asynchronous document work and poll its request status using Python and the API Polling Tool. This Poll for API Request Status tutorial keeps the official sample intact and breaks down authentication, payload construction, endpoint behavior, and result handling for Python.

Why Poll for API Request Status with Python?

Batch pipelines often submit work that may outlast a convenient synchronous HTTP window. API Polling lets Python receive a lightweight request identifier, continue other tasks, and return for the completed response later.

A data-processing job converting a large archive to PDF/A can submit one item, retain its request ID in the batch record, and periodically inspect status while other documents move through the queue. This avoids tying progress to one continuously open connection.

The sample demonstrates the pattern with /pdfa, but the polling contract applies to supported pdfRest processing requests generally. The Response-Type header changes the immediate response shape; it does not change the operation being performed.

Python Code Example

from requests_toolbelt import MultipartEncoder
import requests
import json
import time

# By default, we use the US-based API service. This is the primary endpoint for global use.
api_url = "https://api.pdfrest.com"

# For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
# For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
#api_url = "https://eu-api.pdfrest.com"

api_key = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' # place your api key here

pdfa_endpoint_url = api_url+'/pdfa'

mp_encoder_pdfa = MultipartEncoder(
    fields={
        'file': ('file_name.pdf', open('/path/to/file.pdf', 'rb'), 'application/pdf'),
        'output_type': 'PDF/A-1b',
    }
)

# Send a request to a pdfRest tool with the Response-Type header to get a request ID,
pdfa_headers = {
    'Accept': 'application/json',
    'Content-Type': mp_encoder_pdfa.content_type,
    'Response-Type': "requestId",
    'Api-Key': api_key
}

print("Sending POST request to pdfa endpoint...")
response = requests.post(pdfa_endpoint_url, data=mp_encoder_pdfa, headers=pdfa_headers)

print("Response status code: " + str(response.status_code))

if response.ok:

    response_json = response.json()
    request_id = response_json["requestId"]
    api_polling_endpoint_url = f'{api_url}/request-status/{request_id}'

    headers = {
        'Api-Key': api_key
    }

    print("Sending GET request to request-status endpoint...")
    response = requests.get(api_polling_endpoint_url, headers=headers)

    print("Response status code: " + str(response.status_code))

    if response.ok:
        response_json = response.json()
        while response_json["status"] == "pending":
            # This example will get the request status every 5 seconds until the request is completed.
            print(json.dumps(response_json, indent = 2))
            time.sleep(5)
            response = requests.get(api_polling_endpoint_url, headers=headers)
            response_json = response.json()
        print(json.dumps(response_json, indent = 2))
    else:
        print(response.text)

Source for Poll for API Request Status: View the Python sample on GitHub.

Breaking Down the Code

Import the HTTP and multipart helpers

from requests_toolbelt import MultipartEncoder
import requests
import json
import time

requests handles the HTTP exchange for Poll for API Request Status, while MultipartEncoder constructs form-data bodies with a boundary that the request header can reuse. The remaining Python modules support the response or timing behavior used specifically by Poll for API Request Status.

Select the pdfRest service region

# By default, we use the US-based API service. This is the primary endpoint for global use.
api_url = "https://api.pdfrest.com"

# For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
# For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
#api_url = "https://eu-api.pdfrest.com"

api_key = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' # place your api key here

The Python configuration keeps the pdfRest hostname separate from each Poll for API Request Status route. Using one regional base URL throughout this Python Poll for API Request Status job keeps its returned identifiers available to later requests.

Prepare the operation and request an ID

mp_encoder_pdfa = MultipartEncoder(
    fields={
        'file': ('file_name.pdf', open('/path/to/file.pdf', 'rb'), 'application/pdf'),
        'output_type': 'PDF/A-1b',
    }
)

# Send a request to a pdfRest tool with the Response-Type header to get a request ID,
pdfa_headers = {
    'Accept': 'application/json',
    'Content-Type': mp_encoder_pdfa.content_type,
    'Response-Type': "requestId",
    'Api-Key': api_key
}

print("Sending POST request to pdfa endpoint...")
response = requests.post(pdfa_endpoint_url, data=mp_encoder_pdfa, headers=pdfa_headers)

print("Response status code: " + str(response.status_code))

if response.ok:

Adding response-type: requestId changes the initial Python processing response into an asynchronous identifier. The Poll for API Request Status operation continues normally while the Python caller prepares its status checks.

Build the status route from the returned ID

response_json = response.json()
    request_id = response_json["requestId"]
    api_polling_endpoint_url = f'{api_url}/request-status/{request_id}'

    headers = {
        'Api-Key': api_key
    }

    print("Sending GET request to request-status endpoint...")
    response = requests.get(api_polling_endpoint_url, headers=headers)

    print("Response status code: " + str(response.status_code))

    if response.ok:
        response_json = response.json()
        while response_json["status"] == "pending":

The Python code places the returned request ID into /request-status/{requestId} and authenticates the GET call. Within the Python Poll for API Request Status flow, this tracks processing state rather than an uploaded or generated file resource.

Wait and check until processing finishes

while response_json["status"] == "pending":
            # This example will get the request status every 5 seconds until the request is completed.
            print(json.dumps(response_json, indent = 2))
            time.sleep(5)
            response = requests.get(api_polling_endpoint_url, headers=headers)
            response_json = response.json()
        print(json.dumps(response_json, indent = 2))
    else:
        print(response.text)

The Python status request addresses /request-status/{requestId} and repeats while the state is pending. A production Python Poll for API Request Status implementation should impose a deadline and handle every terminal error explicitly.

Beyond the Tutorial

You can now separate pdfRest submission from completion in Python, retain the returned request ID, and retrieve the terminal response on your own schedule.

Add a deadline, backoff policy, and logging around every request ID. If the process restarts, durable storage should provide enough context to resume checking rather than submit duplicate document work unnecessarily.

Try the Poll for API Request Status workflow with a representative file in API Lab, then adapt the request in Python. The API Polling Tool documentation provides the complete Python context for Poll for API Request Status values, defaults, and limitations.

How to Poll for API Request Status with Python