The shape of the page / options.page_ranges
Render only some pages of a PDF
A range expression that limits the output to specific pages of the rendered document.
What it is for
Useful when one source document produces something that has to be split for different audiences: a report whose first two pages go to a client and whose appendix does not, or a contract where only the signature page is sent for signing.
The request
Sent to options.page_ranges. Everything else on this page is what happens around it.
{
"url": "https://example.com/reports/2026-q1",
"options": {
"format": "A4",
"page_ranges": "1-3, 8, 12-"
}
}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.
- Passed through as a string, so the syntax is the familiar comma-separated list of single pages and hyphenated ranges.
- The document is fully rendered first and then filtered, so a range does not make the render cheaper or faster.
- One document is metered regardless of how many pages come out.
What failure looks like
A range that names pages beyond the end of the document produces a shorter output rather than an error, so asking for pages 1 to 10 of a four page document returns four pages. If your code assumes the count, check it.
When this is the wrong tool
When the page numbers are not stable. A range is positional, and the position of the appendix in a report depends on how many line items were in the table above it. If the split point depends on content, split the content before rendering rather than slicing pages afterwards.
Frequently asked
Is page ranges 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.
Scale PDF output from an API request
A multiplier applied to the whole rendered page, clamped between 0.1 and 2.
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.