GET /jobs/

When the system is at maximum capacity, any conversion endpoint (/convert, /convert/raw, /convert/from-url, /convert/stream, /convert/stream-from-url, /convert/accelerated) may return 202 Accepted instead of 200. This means that your request was accepted and queued for processing as soon as there is capacity. The 202 response includes a job_id and a URL to query the status:

{
  "accepted": true,
  "auto_async": true,
  "job_id": "a1b2c3d4-e5f6-...",
  "status": "queued",
  "status_url": "/jobs/a1b2c3d4-e5f6-...",
  "retry_after_seconds": 5,
  "message": "All backends are at capacity. Your request has been queued..."
}

Check status

GET /jobs/{job_id}
x-api-key: YOUR_API_KEY

Possible answers

queued
processing
completed
failed

The job is queued, waiting for a free backend.

{
  "job_id": "a1b2c3d4-...",
  "status": "queued",
  "created_at": 1719763200000
}

A backend is processing the conversion.

{
  "job_id": "a1b2c3d4-...",
  "status": "processing",
  "started_at": 1719763205000
}

The conversion is over. The body field contains the result (Markdown or JSON depending on the original parameters).

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "http_status": 200,
  "headers": { "content-type": "text/markdown; charset=utf-8" },
  "body": "# My document\n\nConverted content...",
  "completed_at": 1719763210000
}

The conversion failed after several retries.

{
  "job_id": "a1b2c3d4-...",
  "status": "failed",
  "error": "All backends returned 503",
  "failed_at": 1719763220000
}

Recommended polling

Receive 202 → wait retry_after_seconds (5s by default).
Call GET /jobs/{job_id}.
If status is queued or processing, wait 5s and repeat.
If status is completed, use body as the result.
If status is failed, retry the original conversion with backoff.

import requests, time

r = requests.post("https://api.markpdf.tech/convert/raw",
    headers={"x-api-key": "TU_KEY", "content-type": "application/pdf"},
    data=pdf_bytes)

if r.status_code == 202:
    job = r.json()
    while True:
        time.sleep(job.get("retry_after_seconds", 5))
        status = requests.get(
            f"https://api.markpdf.tech/jobs/{job['job_id']}",
            headers={"x-api-key": "TU_KEY"}
        ).json()
        if status["status"] == "completed":
            markdown = status["body"]
            break
        if status["status"] == "failed":
            raise Exception(status["error"])
else:
    markdown = r.text

const res = await fetch("https://api.markpdf.tech/convert/raw", {
  method: "POST",
  headers: { "x-api-key": "TU_KEY", "content-type": "application/pdf" },
  body: pdfBuffer,
});

if (res.status === 202) {
  const job = await res.json();
  let status;
  do {
    await new Promise(r => setTimeout(r, (job.retry_after_seconds || 5) * 1000));
    const poll = await fetch(`https://api.markpdf.tech/jobs/${job.job_id}`, {
      headers: { "x-api-key": "TU_KEY" },
    });
    status = await poll.json();
  } while (status.status === "queued" || status.status === "processing");

  if (status.status === "completed") {
    const markdown = status.body;
  } else {
    throw new Error(status.error);
  }
} else {
  const markdown = await res.text();
}

The results of completed jobs remain available for approximately 1 hour. They can then expire. If you receive 404 when querying a job, resend the conversion.

The 202 is automatic and transparent — you don’t need to activate it. It only happens when all backends are saturated. Under normal conditions, you will always receive 200 directly.

Reference

GET /jobs/{id}

GET /jobs/

Check status

Possible answers

Recommended polling

​GET /jobs/

​Check status

​Possible answers

​Recommended polling

GET /jobs/

Check status

Possible answers

Recommended polling