Conversions
Retrieve conversion status and results via GET /conversions/{id}.
Retrieve the current status and result of a conversion. For completed conversions, the response includes the Markdown output. For pending or processing conversions, poll this endpoint until the conversion completes.
GET https://markdownanything.com/api/v1/conversions/{id}Path Parameters
Prop
Type
Response by Status
The response shape varies depending on the conversion status. The following fields are always present:
Prop
Type
A completed conversion includes the Markdown output and optional metadata.
{
"id": "9e5fcd8a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"status": "completed",
"original_filename": "document.pdf",
"created_at": "2025-01-15T10:30:00+00:00",
"markdown": "# My Document\n\nConverted content here...",
"completed_at": "2025-01-15T10:30:05+00:00",
"metadata": {
"title": "My Document",
"author": "Jane Doe",
"page_count": 3
},
"webhook_delivered": true,
"can_retry_webhook": false
}The metadata field is only included when include_metadata was set to true during the conversion request.
The conversion is actively being processed.
{
"id": "9e5fcd8a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"status": "processing",
"original_filename": "document.pdf",
"created_at": "2025-01-15T10:30:00+00:00",
"started_at": "2025-01-15T10:30:01+00:00",
"webhook_delivered": false,
"can_retry_webhook": false
}The conversion is queued and waiting to be processed.
{
"id": "9e5fcd8a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"status": "pending",
"original_filename": "document.pdf",
"created_at": "2025-01-15T10:30:00+00:00",
"webhook_delivered": false,
"can_retry_webhook": false
}The conversion encountered an error. Credits are automatically refunded for failed conversions.
{
"id": "9e5fcd8a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"status": "failed",
"original_filename": "document.pdf",
"created_at": "2025-01-15T10:30:00+00:00",
"error": "Unable to extract text from the provided file.",
"completed_at": "2025-01-15T10:30:03+00:00",
"webhook_delivered": false,
"can_retry_webhook": false
}Failed conversions are automatically refunded. See Errors for details on auto-refund behavior.
Polling Pattern
If you are using async mode without webhooks, or as a fallback, you can poll the conversion status endpoint. Use exponential backoff to avoid hitting rate limits.
async function pollConversion(id, token, maxAttempts = 30) {
const url = `https://markdownanything.com/api/v1/conversions/${id}`;
for (let i = 0; i < maxAttempts; i++) {
const response = await fetch(url, {
headers: { Authorization: `Bearer ${token}` },
});
const data = await response.json();
if (data.status === "completed") {
return data.markdown;
}
if (data.status === "failed") {
throw new Error(data.error);
}
// Exponential backoff: 1s, 2s, 4s, 8s... capped at 30s
const delay = Math.min(1000 * Math.pow(2, i), 30000);
await new Promise((resolve) => setTimeout(resolve, delay));
}
throw new Error("Polling timed out");
}import time
import requests
def poll_conversion(conversion_id, token, max_attempts=30):
url = f"https://markdownanything.com/api/v1/conversions/{conversion_id}"
headers = {"Authorization": f"Bearer {token}"}
for i in range(max_attempts):
response = requests.get(url, headers=headers)
data = response.json()
if data["status"] == "completed":
return data["markdown"]
if data["status"] == "failed":
raise Exception(data["error"])
# Exponential backoff: 1s, 2s, 4s, 8s... capped at 30s
delay = min(2 ** i, 30)
time.sleep(delay)
raise Exception("Polling timed out")For production use, prefer webhooks over polling. Webhooks deliver results immediately without the overhead of repeated requests.
Error Responses
| Status | Error Code | Description |
|---|---|---|
401 | — | Missing or invalid Bearer token |
404 | not_found | Conversion not found or belongs to a different workspace |
{
"error": "not_found",
"message": "Conversion not found."
}