Conversions

GET /v1/conversions pages with the opaque next_cursor it returns (pass it back as cursor). Each item is the same envelope POST /v1/convert/{name} returns, without the files list.

Page through this when a conversion has more than the 100 source files inlined in GET /v1/conversions/{id}. Read a finished output with GET /v1/conversions/{id}/files/{file_id}/content, which streams the raw bytes by the file's own MIME type — no JSON envelope to unwrap.

The stream sends event: file with { file_id, status } as each source file changes state, event: conversion with the summary envelope when the overall status or counts change, then a final event: conversion and event: end once the conversion reaches a terminal status. It replays the current snapshot on connect, so a late subscriber never misses the outcome.

Deleting removes the conversion record and its stored files. It does not interrupt a source file that is already parsing, but any file that has not started yet is settled as failed and refunded instead of running. Retry only accepts a failed source file; it re-reserves that file's credits and moves the conversion back to running.

A conversion is queued, then running while at least one source file is still working, and then a terminal status: completed (every file succeeded), completed_with_errors (some succeeded, some failed), or failed (none succeeded) — checking status alone never hides a partial failure. A source file's own error is a problem object with a stable code such as document_unprocessable or parser_unavailable; a failed file is not charged. Results are deleted after 24 hours by default; send store: true on the submission to keep them in your library for your plan's retention window.

Long polling with GET /v1/conversions/{id}?wait=100 is the simplest: one request returns as soon as the conversion settles or the wait ends. Use the SSE stream when you show progress to a person, especially for a submission with several source files. Use webhooks for server-side pipelines that should not hold connections open — send many files in one POST /v1/convert/{name} call instead of starting many separate conversions.