Jobs

Check a conversion's status and find out why one failed.

Every conversion is a job. POST /v1/convert returns one, and you can read it any time:

curl https://api.docbeast.com/v1/jobs/job_cbff845fa8cb4e0a9f3d26b14c7e5a10

{
  "id": "job_cbff845fa8cb4e0a9f3d26b14c7e5a10",
  "status": "running",
  "filename": "list.pdf",
  "page_count": null,
  "pages_converted": 0,
  "pages_skipped": 0,
  "error": null,
  "created_at": "2026-11-09T10:44:51Z",
  "expires_at": "...",
  "downloads": null
}

Fields

Field	Meaning
`id`	The job's id. It's all that's needed to read the result, so keep it private.
`status`	`queued`, `running`, `done` or `failed`.
`filename`	The name you gave the file, or `null`.
`page_count`	Pages in the document, once known.
`pages_converted`	Pages read successfully. Only these count against your account.
`pages_skipped`	Pages left out because of a page limit.
`error`	`{ "code", "message" }` when `status` is `failed`, otherwise `null`.
`created_at`	When the job started, in UTC.
`expires_at`	When the job and its files are deleted.
`downloads`	Links to `json`, `csv` and `xlsx` files when `status` is `done`, otherwise `null`.

Waiting for a result

A job can wait in the queue while other files are ahead of it. For a job that isn't finished after wait, poll GET /v1/jobs/{id} every few seconds until status is done or failed.

A job that hits a temporary problem is retried automatically, and can go back to queued while it waits.

When a job fails

A failed job is still a 200 from GET /v1/jobs/{id}, with status set to failed. If you were waiting on POST /v1/convert when it failed, that response is a 422.

Error code	Message
`unreadable_file`	The file couldn't be opened. Check that it isn't password-protected or damaged.
`quota_exceeded`	No pages left on this account or key.
`conversion_failed`	The document couldn't be converted. You weren't charged. Try again in a few minutes.
`upload_missing`	The uploaded file is no longer available.

A failed job costs nothing, and a free conversion that failed is given back.

Expiry

Files and jobs are deleted automatically after a short time. expires_at tells you when. After that, the job answers 404.