PDF output
Pass format=pdf to the take endpoint to print a web page as a PDF instead of taking a screenshot. The page is loaded in a headless Chromium browser, with JavaScript, as for a screenshot, and then printed with the options on this page. To print HTML that your application generates, such as an invoice, send it to POST /v1/take, see Render HTML.
Billing
Every PDF counts as one request against your quota, also with upload=1; the X-Cost header of the response says so. A PDF that fails (time limit, validation error, unreachable website) is not billed. Your quota is checked before the page is rendered: if it does not cover the request, the API answers 429 with quota.required in the body.
Your first PDF
The response is the PDF itself (application/pdf), served as a download.
PDF of a web page
curl -G https://api.screenshotbase.com/v1/take \
-H "apikey: YOUR-API-KEY" \
--data-urlencode "url=https://example.com" \
-d format=pdf \
-d pdf_paper_format=A4 \
-d pdf_margin=15mm \
-o page.pdf
Check the status code before you save the body: errors come back as JSON (see status codes).
Paper size and orientation
pdf_paper_format sets the paper: A4 (default), A0, A1, A2, A3, A5, A6, Letter, Legal, Tabloid (11 x 17 in) or Ledger (17 x 11 in), in any letter case. Set pdf_landscape=1 to turn the paper to landscape.
For any other size, set pdf_width and pdf_height as CSS lengths (mm, cm, in or px), for example pdf_width=100mm&pdf_height=150mm for a shipping label. Each is at most 200in; one of them alone replaces only that side of the paper format. pdf_landscape still turns the page. The margins must leave at least 1in of the page each way, or the request is refused with a 422.
The size and orientation you set win over the page's own CSS (@page { size: A5 landscape }), and so do margins you set (@page { margin }); what you leave out, the page's CSS may still set. Set pdf_prefer_css_page_size=1 to print in the size the page's CSS asks for instead.
Margins
The default margin is 0, so the content reaches the edge of the paper unless the page's own print stylesheet adds space. Set pdf_margin to a CSS length in mm, cm, in or px (a bare number is px):
pdf_margin=15mm: 15mm on every side;pdf_margin=10mm 20mm: 10mm at the top and bottom, 20mm left and right (2 to 4 lengths work as in the CSS margin shorthand);pdf_margin_top,pdf_margin_right,pdf_margin_bottomandpdf_margin_leftoverride a single side.
Each side is at most 4in. Other units, such as em, are refused with a 422.
Print or screen styles
By default the page is printed with its print stylesheet (pdf_media_type=print), as "Save as PDF" in a browser does. Some sites hide navigation, banners and buttons in print. Set pdf_media_type=screen to print the page as it looks on screen instead.
Background colors and images are printed by default; set pdf_print_background=0 to leave them out. pdf_scale (0.1 to 2, default 1) scales the rendering, for example 0.8 to fit wide content on the page.
Page ranges and the 200-page limit
A PDF has at most 200 pages. Longer documents end after page 200, and the response says so with the header X-Pdf-Truncated: pages. Use pdf_page_ranges to pick pages, as in a print dialog:
pdf_page_ranges=1: the first page only;pdf_page_ranges=1-3,5: pages 1 to 3 and page 5;pdf_page_ranges=8-: page 8 to the end (at most page 200).
Ranges are cut at page 200. A selection with no page among the first 200 (for example 201-210) is refused with a 422 before anything is rendered. A selection with no page of the rendered document (for example 25-28 for a page that prints on 8 pages) answers 422 with the message The pdf_page_ranges select no page of the rendered document., and is not billed.
The response with a PDF that was cut carries X-Pdf-Truncated: pages when it ends at page 200 while the document went on, height when pdf_fit_one_page reached the tallest page (200 inches). A PDF that was not cut has no such header. Finding out whether a document of exactly 200 pages goes on takes a second print; when the render's time is too short for it, the PDF comes without the header. An async job says the same in its status and webhook (result.pdf_truncated) and on its result download (the header). A long PDF also takes longer: print one of a hundred pages or more as an async job.
One long page
pdf_fit_one_page=1 prints the whole page on a single PDF page: as wide as the paper (pdf_paper_format, turned by pdf_landscape) and as tall as the content. This suits receipts, long articles or pages you want to archive in one piece. The page is at most 200 inches tall (the size PDF viewers accept); anything below that is cut, and the response says so with X-Pdf-Truncated: height. pdf_page_ranges does not apply.
The whole page means the page as it looks on screen at your viewport_height, printed:
- Sections as tall as the screen (a
100vhhero, a layout withmin-height: 100vh) keep the height they have atviewport_height(default 800 px). On a printed page they would grow with the page and never fit. - Forced page breaks (
break-before: page,page-break-after: always) are ignored: there is only one page. - The page's own
@pagesize and margins are ignored; the margins arepdf_margin.
Headers and footers
pdf_header_template and pdf_footer_template print HTML at the top and bottom of every page, for running titles and page numbers. Send them in the JSON body of a POST (at most 16 KB each); in a query string they are refused with a 422. These placeholders are filled in on every page:
| Placeholder | Becomes |
|---|---|
{page} | the page number |
{total} | the number of pages |
{date} | the date and time of the print |
{title} | the page's title |
{url} | the page's URL (https://html.screenshotbase.invalid/ for HTML input) |
{
"url": "https://example.com/report",
"format": "pdf",
"pdf_margin": "20mm 15mm",
"pdf_header_template": "<div style=\"padding:0 15mm;color:#666\">{title}</div>",
"pdf_footer_template": "<div style=\"width:100%;text-align:center\">Page {page} of {total}</div>"
}
A template is laid out across the whole width of the paper with 10px text; set your own sizes and padding with inline styles. It is printed inside the top (or bottom) margin, which is raised to at least 0.5in when it is smaller; give a taller template a larger margin. A template loads nothing: use inline styles and data: images. One that loads a style sheet, an @import or a web font cannot be printed and answers 422 (not billed). Scripts in a template do not run.
Outline and tags
PDFs are tagged by default: their structure (headings, paragraphs, lists, tables) is written into the file for screen readers, text extraction and search. Set pdf_tagged=0 for a smaller file; a long, tagged document can be several times larger.
Set pdf_outline=1 to add an outline: the bookmarks a PDF viewer shows in its sidebar, one for each heading (h1 to h6) of the page, nested as the headings are. The outline needs the tags, so pdf_outline=1 with pdf_tagged=0 is refused.
Page breaks
Where a page breaks is up to the page's CSS (break-before, break-after, break-inside). Every PDF also knows three helper classes you can put into your HTML:
| Class | Effect |
|---|---|
sb-page-break | a new page after the element |
sb-page-break-before | a new page before the element |
sb-avoid-break | the element is not split across two pages (if it fits on one) |
<section class="sb-avoid-break">
<h2>Totals</h2>
<table>...</table>
</section>
<div class="sb-page-break"></div>
<h1>Appendix</h1>
With pdf_fit_one_page=1 there is only one page: forced breaks, these included, are ignored.
Time limit
A PDF must be rendered within 110 seconds of the start of the request: loading the page, the delay (at most 30 seconds), and printing. A render that takes longer is stopped and answered with 408, the error code target_timeout and the message The target website took too long to load.; it is not billed. A timeout longer than what is left of the 110 seconds is cut to it. Through the MCP server, a tool call must finish within about 12 seconds, and delay is at most 7 there.
If a page runs into the limit, try wait_until=domcontentloaded instead of waiting for every resource, or a shorter delay. A page that needs longer can be printed as an async job, with up to 300 seconds.
Store the PDF
With upload=1, the PDF is stored and the response is a JSON object with its public URL ({"url": "https://cache.screenshotbase.com/screenshots/..."}) instead of the file. The PDF costs the same either way. Without upload=1, the PDF is returned and not stored. If the PDF was rendered but could not be stored, the API answers 503 with The file could not be stored. Please try again.; that request is not billed.
Through the MCP server, a PDF of up to 3 MB arrives as an embedded resource in the tool result; for a larger one, AI agents pass upload: true and use the URL.
Other parameters
The parameters that prepare the page work as for screenshots: wait_until, delay, block_cookie_banners, block_ads, block_chats, hide_selectors, styles and ip_country_code. attachment_name sets the filename of the download (attachment_name=invoice-42 gives invoice-42.pdf). The image options quality and full_page are ignored for PDFs.
Sandbox keys
A sandbox API key returns a placeholder PDF without rendering the page, at no cost (X-Cost: 0). Use it to test your integration; use a live key for the real document.