How to Save a Browserless Webpage Screenshot as a PDF
Browserless screenshots are images, while its PDF endpoint uses Chrome’s print engine. Choose the right workflow to preserve pixels or create a printable PDF.
Browserless’s /screenshot endpoint returns an image, not a PDF. To put the captured pixels in a PDF, save the image and convert it with a separate image-to-PDF tool. If you want a conventional, printable PDF of the page, send the URL to Browserless’s /pdf endpoint instead; Chrome’s print engine renders it, and the result can contain selectable text. Browserless Screenshot API · Browserless PDF API
Choose the output you actually need
| Need | Endpoint or workflow | What it produces |
|---|---|---|
| Keep the screenshot’s appearance and pixels | /screenshot, then convert the image separately |
PNG, JPEG, or WebP inside a PDF |
| Create a normal document for printing or text selection | /pdf |
A print-rendered PDF, with selectable text when the page markup supports it |
| Create one continuous PDF page for a long webpage | A custom /function flow |
A custom PDF; the regular /pdf endpoint does not create one continuous long page |
A full-page screenshot and a continuous one-page PDF are different outputs. Browserless documents full-page capture for screenshots; its PDF endpoint uses Chrome’s print pagination behavior. See the Browserless screenshots and PDFs guide.
Capture a webpage image with Browserless
- Get an API token from your Browserless account dashboard.
- Use the REST endpoint host configured for your deployment. The example below uses Browserless’s documented SFO production host.
- POST a JSON body containing the page URL and screenshot options. The response is image bytes, so save it with an image extension.
- Convert that saved image to PDF using an image-to-PDF tool available in your environment. The Browserless documentation describes image output but does not prescribe a particular converter or command.
curl -X POST \
"https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE" \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://example.com/",
"options": { "fullPage": true, "type": "png" }
}' \
--output "screenshot.png"Replace the token and target URL. If your Browserless deployment uses another endpoint hostname, use that hostname. This request saves a full-page PNG; it does not make a PDF. Choose PNG when preserving crisp text and fine detail matters. JPEG is useful when a smaller lossy image is acceptable, while WebP is another supported image format. The endpoint’s documented settings also cover viewport and clipping, quality, and waiting behavior. Consult the screenshot API reference for the exact options supported by your deployment.
Convert the image to a PDF
Use a separate image-to-PDF converter after the screenshot completes. Choose page dimensions and fit behavior deliberately: fitting the image to a standard paper page can scale it, while a PDF page sized to the image can preserve its pixel dimensions more directly. For long full-page screenshots, a standard paper-sized PDF may make text small; consider splitting the image across pages if readability matters. These are conversion choices, not Browserless screenshot endpoint options.
Keep the original image as the source artifact. If the conversion fails, you can retry that step without paying for another browser capture or changing the capture request.
Generate a printable PDF directly
When you need a document rather than a pixel-preserving screenshot, call /pdf and save its PDF response. It accepts a URL or HTML and uses Chrome’s print engine. The resulting layout can follow print stylesheets and may differ from what a screen screenshot shows.
curl -X POST \
"https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN_HERE" \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/"}' \
--output "page.pdf"Use the endpoint host configured for your account if it differs from the SFO example. The request body can provide a URL or HTML according to the PDF API documentation. Verify the returned file is a PDF before processing it downstream.
Print-specific options and limits
printBackground: trueincludes page background graphics in the print output.- To favor screen styling over print CSS, emulate screen media in the browser PDF flow. Browserless’s BAP example also shows
waitForFonts: truefor pages whose fonts need to load before printing. - The regular PDF endpoint does not produce one endless page for a long webpage. Use a custom
/functionflow when a continuous page is a requirement. - PDF tagging can embed structure tags when requested, but the result depends on source markup and is not certified PDF/UA output.
- PDF metadata such as title and author is not directly exposed through the underlying Puppeteer/Chrome print interface described in the docs; post-processing is documented as a workaround.
These print options apply to PDF generation. They do not change the fact that /screenshot returns image data. See Browserless’s BAP screenshots and PDFs guide and its PDF API reference.
Choose between screenshot-to-PDF and print-to-PDF
| Question | Use screenshot, then convert | Use /pdf |
|---|---|---|
| Must the PDF look like the captured screen? | Yes; the PDF contains the captured image | Not necessarily; print CSS and pagination can change the layout |
| Should text remain selectable? | Usually no; the page is an image | Potentially yes, depending on the page and rendered output |
| Does Browserless return a PDF from this request? | No, it returns an image; conversion is separate | Yes, this endpoint returns a PDF |
| Can it make one continuous page for a long page? | The screenshot can be full-page, but the image-to-PDF tool determines PDF page layout | No, the standard endpoint paginates; custom handling needs a function flow |
Performance, reliability, and cost considerations
- Capture time: Full-page capture and waiting for page content can take longer than a viewport capture. Wait only for the content your workflow needs; use the endpoint’s documented waiting controls for dynamic pages.
- Output size: Full-page PNGs can be large. JPEG or WebP may reduce image size, with format-specific quality tradeoffs. Image dimensions and chosen PDF page layout affect the final document size.
- Reliability: Check the HTTP status and resulting file type before treating a response as a valid image or PDF. Keep capture and conversion as separate steps so either can be retried independently.
- Cost: Browserless requests require an API token. The documentation reviewed for this workflow does not establish prices, so check your account’s current plan and usage terms. No capture or conversion benchmark is claimed here.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| The saved “PDF” is actually an image | You called /screenshot; it returns PNG, JPEG, or WebP bytes |
Convert the image with a separate tool, or call /pdf for a print-rendered PDF. |
| The request is rejected or unauthorized | The token is missing or invalid, or the endpoint host does not match your deployment | Check the dashboard token and configured host; send the token as the documented token query parameter. |
| The screenshot is blank or misses content | The page may still be loading dynamic content, or the chosen viewport/clip excludes it | Use an appropriate wait option and review viewport, full-page, and clip settings in the screenshot API reference. |
| The PDF differs from the screenshot | The PDF uses print rendering and print styles, while the screenshot captures rendered screen pixels | Use screenshot plus image conversion when visual fidelity to the capture is required; for PDF generation, consider background printing or screen media emulation where appropriate. |
| A long PDF is split across pages | The standard PDF route uses print pagination | Use a custom function flow if the required format is one continuous page, or retain ordinary pagination for a printable document. |
| The image-to-PDF conversion fails | The input file may be incomplete, unsupported by the converter, or too large for its limits | Confirm the capture completed and the file is a supported image; try another supported format or adjust image/PDF dimensions. |
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. Its one-call API returns a screenshot image; it is not a Browserless-compatible PDF endpoint. For a PDF, convert the returned image separately or use ScreenshotNeo’s PDF capture options when their print-style output fits your need. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Can Browserless’s screenshot API return a PDF directly?
No. The screenshot endpoint returns image data. Use the PDF endpoint for print-rendered PDFs, or convert the screenshot image separately.
Will a screenshot-based PDF have selectable text?
Typically the page content is represented by image pixels, so it will not behave like text rendered into a PDF. Use the print PDF route when text selection is important.
Can I supply HTML instead of a URL?
Browserless documents URL or HTML input for the PDF operation. The screenshot endpoint also accepts HTML according to its documentation.
Does full-page screenshot mean one-page PDF?
No. Full-page describes the screenshot capture. The PDF converter controls how that image is placed on PDF pages, and Browserless’s regular PDF route paginates rather than creating one continuous page.
Sources: Screenshot API, PDF API, Screenshots and PDFs with BAP, and OpenAPI overview.
