Streaming and asynchronous jobs

As in API, there are two different mechanisms:

Response Streaming (/convert/stream): Progressive Markdown fragments while the server converts, reading the file direct from disk with Bun.file.
Jobs due to saturation (202): when all backends are busy, the request is queued and responded to 202 with a job_id. See GET /jobs/{id}.

Streaming with `convertStream`

const client = new MarkpdfClient({ apiKey: "YOUR_API_KEY" });

for await (const chunk of client.convertStream("./report.pdf")) {
  process.stdout.write(chunk);
}

convertStream is a AsyncGenerator<string> — use it with for await...of. Internally it opens Bun.file(path) and streams it to the body of POST /convert/stream, so the entire file is never loaded into memory before being sent.

for await (const chunk of client.convertStream("./report.pdf", { slim: true })) {
  handle(chunk);
}

Bun.serve({
  async fetch(req) {
    const url = new URL(req.url);
    const pdfPath = url.searchParams.get("path")!;

    const stream = new ReadableStream({
      async start(controller) {
        const encoder = new TextEncoder();
        for await (const chunk of client.convertStream(pdfPath)) {
          controller.enqueue(encoder.encode(chunk));
        }
        controller.close();
      },
    });

    return new Response(stream, { headers: { "content-type": "text/markdown" } });
  },
});

`streamSlimStrategy`

client.convertStream("./report.pdf", { slim: true, streamSlimStrategy: "sampled" });

"off": pure streaming per page, without noise detection. TTFB minimum.
"sampled" (default): Sample the first few pages, then output per page.
"full": materializes the entire document before issuing. Better cleaning, worse TTFB.

See Parameters.

Jobs due to saturation (202)

By default, convertFile, convertBytes and convertFromUrl handle 202 transparently (autoPoll: true on the client):

// SDK waits and polls automatically
const markdown = await client.convertFile("./report.pdf");

Poll manual

import { MarkpdfJobQueuedError } from "@markpdf/bun";

try {
  const markdown = await client.convertFile("./report.pdf", { autoPoll: false });
} catch (err) {
  if (err instanceof MarkpdfJobQueuedError) {
    console.log(`En cola: ${err.jobId}`);
    const status = await client.waitForJob(err.jobId, { pollIntervalMs: 5000 });

    if (status.status === "completed") {
      const markdown = status.body as string;
    } else {
      throw new Error(status.error);
    }
  } else {
    throw err;
  }
}

waitForJob is equivalent to calling getJob in a loop respecting retry_after_seconds, but encapsulated.

Under normal load conditions you won’t see 202 — it only happens when all backends are saturated. autoPoll: true (the default) already covers it without additional code in most cases.

Results for completed jobs expire in approximately 1 hour. If you save a jobId and receive 404 when querying it, resend the original conversion.

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Streaming and asynchronous jobs

Streaming and asynchronous jobs

Streaming with `convertStream`

`streamSlimStrategy`

Jobs due to saturation (202)

Poll manual

​Streaming and asynchronous jobs

​Streaming with convertStream

​streamSlimStrategy

​Jobs due to saturation (202)

​Poll manual

Streaming and asynchronous jobs

Streaming with `convertStream`

`streamSlimStrategy`

Jobs due to saturation (202)

Poll manual