The shape of the page / options.scale
Scale PDF output from an API request
A multiplier applied to the whole rendered page, clamped between 0.1 and 2.
What it is for
A blunt instrument, and occasionally the right one. Its honest use is fitting a layout that was designed for a screen onto paper without rewriting the CSS, which is a real situation when the source is an application you do not control.
The request
Sent to options.scale. Everything else on this page is what happens around it.
{
"url": "https://example.com/dashboard",
"options": {
"format": "A4",
"landscape": true,
"scale": 0.75
}
}The actual limits
Read from the implementation rather than remembered, so these are the numbers the API enforces rather than the ones a roadmap intends.
- Values below 0.1 are clamped to 0.1 and values above 2 are clamped to 2. A non-numeric value falls back to 1 rather than erroring.
- The default is 1.
- Scaling applies to the rendered output, so it scales hairlines and font sizes along with everything else.
What failure looks like
It never errors, which is the risk. A 0.6 scale shrinks a 0.5pt rule to 0.3pt, and plenty of printers drop a rule that thin entirely. It also shrinks type below the size it was designed at, so a document that looked fine in review is unreadable in someone's hand.
When this is the wrong tool
Any time you control the stylesheet. Scaling is a way of avoiding a layout decision, and the layout decision is almost always the better fix: a smaller base font size, a narrower measure, or a larger page. Scale is for documents you cannot edit.
Frequently asked
Is scale available on the free plan?
Yes. There is no plan gate on this one: it behaves the same on the free plan as on every paid plan, and the only limit that applies is the monthly document allowance.
Where do these numbers come from?
The running implementation. Every figure on this page, from payload ceilings to per-plan limits, is what the API enforces today rather than what a specification says it should. If one of them is wrong, the API is the thing to believe.
Related capabilities
Options that come up in the same request, and one from each of the other groups.
Set the PDF page size in an API request
Six named paper sizes, passed in the request options, with A4 as the default when nothing is given.
Set PDF margins in an API request
One value for all four sides, or an object naming each side, defaulting to 1cm all round.
Generate a landscape PDF from an API
A boolean that turns the page rather than swapping its dimensions.
Use the CSS @page size instead of a format
Tells the renderer to use the page box the document declares rather than a named format, which is how every non-standard size is reached.
Render an HTML string to PDF over an API
Send a complete HTML document in the request body and get the PDF bytes back in the response.
Print background colours and images in a PDF
Controls whether background colours and images survive into the PDF. On by default here, which is the opposite of a browser's own default.
Render many PDFs in one API call
Up to several hundred documents in one request, each stored and returned as a link, with per-item success or failure rather than one all-or-nothing result.
Password protect a generated PDF
Encrypts the output so a reader is asked for a password before the document opens.
Everything the API does
The full list, grouped by which part of the request it belongs to.
API reference
The complete parameter documentation, including the parts with nothing interesting to say about them.
100 free documents a month, and a playground that runs a real render without a key.