Scale To Fit Parameter

The scale_to_fit parameter applies to PDF output only. When enabled, content wider than the A4 page is scaled down so the whole layout fits the page width instead of being cropped, and any trailing blank page is trimmed from the end of the document.

Specifications

Property	Value
Type	boolean
Required	No
Default	false
Applies to	PDF output only (format: "pdf"); ignored for PNG
API	HTML/CSS and Screenshot APIs

Description

By default, PDF output lays your content out at the A4 page width (roughly 794 CSS pixels). Content that flows naturally reflows to that width, but a fixed-width design wider than the page gets cropped at the right edge.

With scale_to_fit: true:

• The renderer measures the laid-out content first. If it is wider than the A4 page, the whole layout is scaled down to fit the page width, so a fixed 1600px or 2400px design prints complete rather than cropped.
• Because the scaling is vector, text stays selectable and sharp at any zoom level. Nothing is rasterised by the scale step.
• The document’s page count is clamped to what the content actually needs. Fixed-height layouts that overflow a page boundary by a pixel or two normally produce a blank final page; scale_to_fit removes it.
• Content narrower than the page is left at its natural size. The parameter only ever scales down.

One useful consequence: with scale_to_fit the PDF keeps the same proportions as the PNG output for the same request, because the content is laid out at its own width and scaled, rather than reflowed to a narrower page. For Screenshot API captures this means the desktop layout of the page is preserved instead of the narrower layout a plain PDF render would show.

Examples

A fixed-width design, scaled to the page

{
    "html": "<div style='width:1600px'>Wide fixed-width layout</div>",
    "format": "pdf",
    "scale_to_fit": true
}

A web page as a PDF, keeping its desktop layout

{
    "url": "https://example.com/dashboard",
    "width": 1440,
    "format": "pdf",
    "scale_to_fit": true
}

When to use

Turn scale_to_fit on when:

• Your markup is a fixed-width design (a card, a certificate, a wide table) rather than a flowing document, and a plain PDF render crops it.
• A Screenshot API capture should keep the page’s desktop layout in the PDF rather than reflowing to the page width.
• Your PDFs end with a blank page.

Leave it off when the content is written to flow like a document: an invoice or report built from flowing HTML reads better reflowed to the page width at full size than scaled down.

Common mistakes

• Expecting it to enlarge small content. scale_to_fit only scales down. A 600px-wide card stays 600px wide on the page.
• Using it on PNG renders. It has no effect outside PDF mode; use width and height to size images.
• Scaling a long flowing report. A document that reflows cleanly does not need it, and at very wide viewports the scaled text becomes small. Fit the layout to the content, not the other way round.

See also: format, dimensions, webhook_url.