Poll Status

Check the progress and status of a document conversion task.

Endpoint

GET /v1/status/poll/{task_id}

Authentication

All requests require authentication using the X-Api-Key header with your API key.

Path Parameters

Parameter	Type	Required	Description
`task_id`	string	Yes	The task ID returned from a conversion request

Request Headers

Header	Required	Description
`X-Api-Key`	Yes	Your API key for authentication

Response

Success Response (200 OK)

Returns the current status of the conversion task:

{
  "task_id": "abc123def456",
  "task_type": "convert",
  "task_status": "success",
  "task_position": null,
  "task_meta": null,
  "failure": null,
  "error_message": null
}

Field	Type	Description
`task_id`	string	The unique identifier for this task
`task_type`	string	Always `"convert"` for conversion tasks
`task_status`	string	Current status (see Status Values)
`task_position`	integer	Position in queue (null when processing or complete)
`task_meta`	object	Additional metadata (currently unused)
`failure`	object	Failure details if the task failed, otherwise null
`error_message`	string	Error description if status is `"failure"`, otherwise null

Status Values

Status	Description	Next Action
`pending`	Task is queued and waiting to be processed	Continue polling
`processing`	Conversion is currently in progress	Continue polling
`success`	Task completed	Retrieve the conversion results
`failure`	Task failed with an error	Check the `failure` and `error_message` fields for details

Error Responses

See Error Handling for the full error model.

Status	Description
`401`	Unauthorized — missing or invalid API key
`404`	Not found — the task ID doesn't exist or has expired
`429`	Too many requests — rate limit exceeded
`500`	Internal server error

Examples

Find examples of using the Status endpoint in the Examples section.

Poll the status endpoint until task_status is success or failure, using exponential backoff to avoid unnecessary requests. Start at 1–2 seconds and increase the delay up to a cap (for example, 30 seconds).

#!/bin/bash
TASK_ID="abc123def456"
DELAY=1

while true; do
  RESPONSE=$(curl -s -X GET "${DOCLING_SERVICE_URL}/v1/status/poll/${TASK_ID}" \
    -H "X-Api-Key: ${DOCLING_API_KEY}")

  STATUS=$(echo "$RESPONSE" | jq -r '.task_status')

  if [ "$STATUS" = "success" ]; then
    echo "Conversion complete"
    break
  elif [ "$STATUS" = "failure" ]; then
    echo "Conversion failed: $(echo "$RESPONSE" | jq -r '.error_message')"
    exit 1
  fi

  sleep "$DELAY"
  DELAY=$((DELAY * 2))
  [ "$DELAY" -gt 30 ] && DELAY=30
done

The Python SDK polls for you — client.convert(...) submits, polls, and returns the final result, so you don't need to implement this yourself.

Common Issues

Task not found (404) — the task_id is incorrect, was never created successfully, or the task has expired. Verify you're using a task_id returned from a recent conversion request.

Task stuck in pending — a high task_position indicates queue load; the task starts once it reaches the front of the queue. If it stays pending far longer than expected, retry the conversion or contact support.

Polling too frequently (429) — you're exceeding the rate limit. Use exponential backoff (see Polling Best Practices) rather than a tight loop.

Task Lifecycle

Submit — the conversion request returns a task_id
Pending — the task is queued (check task_position)
Processing — conversion in progress
Complete — status is either success or failure; success means the task finished, not necessarily that every document converted
Retrieve — get result artifacts and per-document statuses, or handle the task-level error

Next Steps

Once the status is "success":

Retrieve results - Use the /v1/result/{task_id} endpoint to get result artifacts, download URLs, and document-level statuses
Process the output - Check result counters and document statuses, then download artifacts for successful documents

Convert Source - Convert documents from URLs
Convert File - Upload and convert local files
Get Results - Retrieve converted documents

Poll Status

On this page