HTML to PDF vs Screenshot API: Which Endpoint to Call

Picking between an HTML-to-PDF API and a screenshot API isn't really about file format — it's about which rendering primitive Chrome uses to produce that file. Get the primitive wrong and you'll fight pagination bugs on a report, or ship a blurry, cropped image where a client expected a clean printable document. This guide frames the html to pdf vs screenshot api decision around what's actually happening under the hood, then gives you a parameter table and a decision rule so you can pick correctly on the first request.

Two Endpoints, Two Rendering Models

A headless browser has several ways to "render" a page, and the Chrome DevTools Protocol exposes them as distinct commands. Page.printToPDF runs a print-layout rendering path: it lays the DOM out the way a printer would, honoring @page rules and print media queries, splitting content across discrete pages with margins, headers, and footers. Page.captureScreenshot does something completely different — it takes a pixel snapshot of the DOM exactly as it appears in a rendered viewport at a given width and height, with no concept of pages at all.

That split is why every downstream decision — dimensions, background handling, output format, even how you think about "full page" — flows from a single question: do you need render html to pdf for print/reading, or a raw image of what's on screen? A headless browser pdf vs screenshot endpoint isn't two flavors of the same output; it's two different rendering engines wearing the same API surface. Tools like Puppeteer and Playwright expose both commands directly, which is exactly what Browsevra wraps behind its /pdf and /screenshot endpoints.

When to Reach for the PDF Endpoint

Use the PDF endpoint whenever the output needs to be printed, archived, or read as a document rather than viewed as an image. Concrete cases:

• Invoices and statements — need consistent margins, page numbers, and text that stays selectable and searchable years later.
• Contracts and compliance/archival reports — often required to be reproducible in identical paginated form for audit trails.
• Multi-page documents — anything longer than one screen benefits from @page-aware pagination instead of an arbitrarily long image.
• Downloadable/printable deliverables — anything a user might hit "print" on.

Pagination and text-selectability are the deciding factors here. A PDF built via Page.printToPDF respects print CSS, so a stylesheet with @media print rules controlling font size, column layout, or hidden navigation actually gets applied — something a viewport screenshot has no mechanism for. If you're building web page to pdf report generation and running into layout or font issues, deeper fixes (custom @page margins, page-break control, embedding fonts correctly) are covered in HTML to PDF API: How to Get Pixel-Perfect Output. When to use pdf api comes down to one test: will a human print this or file it away?

When to Reach for the Screenshot Endpoint

Use the screenshot endpoint when the goal is to look at the page, not read it as a document. That covers:

• Visual monitoring and diffing — comparing pixel output over time to catch regressions.
• Social and link previews — the image a chat app or crawler shows when a URL is shared.
• Thumbnails — small, fast-loading representations of a page or dashboard.
• Dashboards and QA snapshots — capturing exact on-screen state for a bug report or a scheduled internal digest.
• Marketing capture — hero images of your own product pulled straight from a live page.

None of these need pagination — they need exact pixel fidelity at a specific viewport size, in PNG, JPEG, or WebP. A screenshot api for reports can work for a single-page visual summary, but the moment a "report" needs to span multiple printed pages with consistent margins, you're better off on the PDF path. The print to pdf vs capture screenshot distinction is really about whether the output has document semantics (pages) or image semantics (pixels). Since both endpoints depend on JavaScript-heavy pages having finished rendering before capture, teams scraping SPAs or dashboards should also check How to Render JavaScript for Scraping SPAs Reliably. If you're scaling capture volume across many URLs, Screenshot API at Scale: A Concurrency & Queue Playbook covers the queueing side.

Request Parameters: What Changes Between the Two Calls

Concern	/pdf endpoint	/screenshot endpoint
Sizing	Page size (A4, Letter) or custom width/height in inches/mm	Viewport width/height in pixels
Layout mode	Paginated, with margins and page breaks	Single continuous image or full-page scroll capture
CSS handling	Print media type, @page rules, print backgrounds toggle	Screen media type, normal responsive CSS
Output format	PDF only	PNG, JPEG, or WebP
Quality/compression	Not applicable (vector/text based)	JPEG/WebP quality parameter
Headers/footers	Optional header/footer templates per page	Not applicable

That table is the practical answer to headless browser pdf vs screenshot endpoint: PDF parameters talk in inches and pages, screenshot parameters talk in pixels and compression. Mixing them up — asking a screenshot call for a "page size" or a PDF call for JPEG quality — is the most common integration mistake.

A Quick Decision Framework

Keep it simple: if the output needs to be printed, archived, or read as a multi-page document, call /pdf. If it needs to be viewed, compared, or embedded as an image, call /screenshot. That single rule answers should i use pdf or screenshot for invoices immediately — invoices are printed and filed, so PDF wins, every time.

Hybrid cases exist. You can screenshot a page and wrap that image inside a PDF container, but that's an image-based PDF — no selectable text, no real pagination, just a picture glued into a PDF wrapper. It's not the same as true print-rendered output from Page.printToPDF, and it will look wrong the moment someone tries to select text or the page is taller than one viewport. For genuine pdf vs image export web page decisions, treat "screenshot-in-a-PDF" as a workaround, not a substitute for the real rendering path.

Try Both Endpoints on the Same Page

The fastest way to settle this for your own use case is to test it directly: send the same URL to Browsevra's /pdf and /screenshot endpoints and compare the outputs side by side. Head to the docs to try the html to pdf api and the screenshot endpoint against a real page, and check pricing to plan costs if you'll be running either at volume.

Frequently Asked Questions

Can I just take a screenshot and convert it to a PDF instead of using a PDF endpoint?

You can, but the result is an image wrapped in a PDF file, not a true print-rendered document — no selectable text, no real pagination, and no respect for @page or print CSS. It works for quick one-off captures but breaks down for multi-page or text-heavy documents like invoices.

Why does my PDF output look different from what I see in the browser viewport?

Because PDF generation uses a print-layout rendering path that applies print media queries and @page rules, which can hide elements, change fonts, or restructure layout compared to what you see on screen. If your page only has screen styles, print rendering may fall back to defaults that look noticeably different.

Does the screenshot endpoint support full-page capture like the PDF endpoint does?

Yes — screenshot endpoints typically support a full-page mode that captures the entire scrollable height of a page as one continuous image, rather than only the visible viewport. This differs from PDF pagination, which splits that same content across discrete printed pages with margins.

Which output format is smaller in file size, PDF or screenshot images?

It depends on content: text-heavy pages usually produce smaller PDFs since text is stored as vector/text data rather than pixels, while JPEG or WebP screenshots can be smaller for image-heavy or photographic content thanks to compression. PNG screenshots tend to be the largest of the common options.

Do I need to handle JavaScript-rendered content differently for PDF vs screenshot requests?

Both endpoints need the page's JavaScript to finish rendering before capture, so the handling is conceptually the same — wait for network idle or a specific selector before triggering either printToPDF or captureScreenshot. Timing requirements don't differ meaningfully between the two output types.

Can one API call return both a PDF and a screenshot of the same page?

Not in a single call — each endpoint triggers a distinct rendering command with different parameters, so you need one request to /pdf and one to /screenshot. Running both against the same URL is still fast and is the recommended way to compare outputs before deciding which to use in production.

Ready to see the difference on your own content? Send a real URL through both endpoints in the docs, compare the PDF and screenshot output side by side, and check pricing once you know which format — or mix of both — your workload needs. browsevra handles the rendering infrastructure so you can focus on shipping the right output the first time.