The shape of the page / options.landscape
Generate a landscape PDF from an API
A boolean that turns the page rather than swapping its dimensions.
What it is for
Orientation is a property of the page, not a different page size, and treating it that way is what lets the format name stay meaningful. A landscape A4 is still A4: the paper in the tray does not change, only the direction the content runs.
The request
Sent to options.landscape. Everything else on this page is what happens around it.
{
"html": "<!doctype html>...",
"options": {
"format": "A4",
"landscape": true
}
}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.
- Boolean, defaulting to false.
- It composes with format rather than replacing it, so A4 landscape and A3 portrait are 297mm wide by different means and both are expressible.
- In the document's own CSS the equivalent is a second keyword on the size descriptor, as in size: A4 landscape.
What failure looks like
No error case. The failure is a design one: a wide table set landscape still overflows if it has too many columns, and landscape is often reached for when the real answer is fewer columns or a smaller type size. Turning the page buys 87mm on A4 and no more.
When this is the wrong tool
When only some pages should be landscape. This is a document-level option, so a report with one wide appendix cannot mix orientations through it. Mixed orientation needs named page masters in CSS, and support for those varies by renderer, so the pragmatic answer is usually to render the appendix as a second document and merge the two.
Frequently asked
Is landscape orientation 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.
Scale PDF output from an API request
A multiplier applied to the whole rendered page, clamped between 0.1 and 2.
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.