API Polling
Introduction
API Polling repeatedly checks the status of a long-running process by making periodic requests to an endpoint. In pdfRest, send a processing request with the Response-Type: requestId header, then use /request-status/{requestId} to check its progress and retrieve the completed response.
2.58.0. Older Container releases do not support API Polling.Prerequisites
Before you start, ensure you have:
- A running pdfRest API Toolkit Container with a configured License Key.
- A document to process, such as a local Word file named
document.docx. - Basic knowledge of HTTP requests and responses.
Container requests do not require a client API key. Configure your License Key when starting the container, as described in Getting Started.
The examples use http://localhost, matching host port 80 in the Docker Compose deployment example. Replace this address with your deployed Container's base URL. Configure PDFREST_SERVER_DOMAIN with the externally reachable base URL so returned resource URLs use the correct address. See Configure Container.
Step-by-step guide
Make the initial request
Send a document to a processing endpoint with Response-Type: requestId. For example, convert a Word document to PDF with /pdf:
curl --request POST "http://localhost/pdf" \
--header "Response-Type: requestId" \
--form "file=@document.docx"
The API returns HTTP 200 with a requestId and a message instead of waiting for the final result. An example response is:
{
"requestId": "11111111-1111-4111-8111-111111111111",
"message": "Request received and is being processed."
}
Save the returned requestId for polling. This identifies the request, not an input or output file.
Poll the /request-status endpoint
Use the returned requestId in the polling URL. Replace the example ID below with your request's ID:
curl --request GET \
"http://localhost/request-status/11111111-1111-4111-8111-111111111111"
While processing continues, the API returns HTTP 200 with status: "pending":
{
"status": "pending",
"requestId": "11111111-1111-4111-8111-111111111111"
}
Wait before polling again, for example five seconds. Continue until status is completed or an error occurs.
Understand the response
Check the JSON status field as well as the HTTP status code:
| Response | Meaning | Next action |
|---|---|---|
HTTP 200, status: "pending" | Processing has not completed. | Wait, then poll again. |
HTTP 200, status: "completed" | The original request has finished. | Inspect the returned payload for results or an error. |
HTTP 400 | The request ID is invalid. | Check the submitted requestId. |
HTTP 404 | The request status record was not found. | Check the ID, storage configuration, and retention settings. |
HTTP 500 | The polling request encountered a server error. | Inspect the error response and Container logs. |
A completed response includes the original processing response. For a successful conversion to PDF, it can look like this:
{
"status": "completed",
"requestId": "11111111-1111-4111-8111-111111111111",
"outputUrl": "http://localhost/resource/22222222-2222-4222-8222-222222222222?format=file",
"outputId": "22222222-2222-4222-8222-222222222222",
"inputId": "33333333-3333-4333-8333-333333333333"
}
A completed status does not guarantee successful processing. Check for an error field before using the output.
Retrieve the final data
After a successful conversion, download the file from the returned outputUrl. For the example above:
curl --output converted-document.pdf \
"http://localhost/resource/22222222-2222-4222-8222-222222222222?format=file"
This saves the processed PDF as converted-document.pdf.
Best practices
- Polling interval: Start with an interval such as five seconds to avoid excessive requests.
- Error handling: Handle HTTP errors and processing errors in completed responses.
- Timeouts: Set request timeouts and an overall polling deadline to prevent indefinite waiting. Processing does not automatically resume after a container stops.
- Retention: Retrieve results before they expire under your file lifecycle policy. Polling does not extend retention.
For endpoint parameters and response schemas, see the Container API Reference Guide.