PDF to Images Status API

Check the status of a PDF-to-images conversion job started with the PDF to Images API. While the conversion is running, the response includes per-page progress entries.

Endpoint	/pdf-to-images-status
URL	https://llmwhisperer-api.us-central.unstract.com/api/v2/pdf-to-images-status
Method	GET
Headers	unstract-key: <YOUR API KEY>

Parameters

Parameter	Type	Default	Required	Description
whisper_hash	string		Yes	The whisper_hash returned when the conversion job was submitted.

Example Curl Request

curl -X GET --location 'https://llmwhisperer-api.us-central.unstract.com/api/v2/pdf-to-images-status?whisper_hash=XXXXXXXXXXXXXXXXXXX' \
-H 'unstract-key: <Your API Key>'

Response

HTTP Status	Content-Type	Description
200	application/json	Job status JSON. Refer below for the format.
400	application/json	No whisper_hash provided, or no job found for the provided hash.

Example 200 Response (processing)

{
    "status": "processing",
    "message": "Converting PDF to images",
    "detail": [
        {
            "page_no": 1,
            "index": 1,
            "total_pages": 4,
            "message": "Converting page 1 of 4"
        },
        {
            "page_no": 2,
            "index": 2,
            "total_pages": 4,
            "message": "Converting page 2 of 4"
        }
    ]
}

page_no is the page's number in the document. index and total_pages count the pages being converted; index differs from page_no when pages_to_extract selects pages, and the message then names the document page, for example Converting page 1 of 2 (document page 10).

Example 200 Response (processed)

{
    "status": "processed",
    "message": "PDF to images conversion complete",
    "metadata": {
        "page_count": 2,
        "pages": [10, 12],
        "total_page_count": 40,
        "format": "png",
        "zip_size_bytes": 812345
    }
}

page_count is the number of page images in the ZIP. pages lists the document page of each image in order (page_001 is document page 10 above), and total_page_count is the document's page count.

Example 200 Response (invalid page selection)

{
    "status": "error",
    "message": "error_in_conversion: invalid_page_range: page range '10-20' selects no pages of this 5-page document; nothing was charged",
    "metadata": {
        "error_code": "invalid_page_range",
        "pages_to_extract": "10-20",
        "total_page_count": 5
    }
}

Example 200 Response (size limit exceeded)

{
    "status": "error",
    "message": "error_in_conversion: size_limit_exceeded: page images exceed max_total_image_bytes=20000000 after 31 of 40 pages (20412816 bytes rendered); nothing was charged",
    "metadata": {
        "error_code": "size_limit_exceeded",
        "max_total_image_bytes": 20000000,
        "rendered_bytes": 20412816,
        "pages_rendered": 31,
        "page_count": 40,
        "format": "png",
        "from_memory": false,
        "rejections_today": 1
    }
}

The job failed because the page images went over the max_total_image_bytes sent with the conversion. See size limit for each field.

Example 400 Response

{
    "message": "Job not found for the provided whisper hash 'XXXX'"
}

Possible Statuses

• accepted: The document has been accepted and queued for conversion.
• processing: The document is being converted. detail carries per-page progress.
• processed: The conversion is complete and the ZIP is ready to be retrieved.
• error: The conversion failed. Check the message for the reason (for example, a document over the 999-page limit). Failures with a metadata.error_code (invalid_page_range, size_limit_exceeded) are not charged.
• retrieved: The result has already been downloaded (see the one-time retrieval note in the retrieve API).

Note: Once the job is processed, the page counts are in metadata (see above). While it is processing, total_pages in the progress entries is the number of pages being converted.