PDF Blocks
PricingSupport
Start Free
Go to Page

Selecting pages

The authoritative reference for choosing pages — set syntax (pages) versus ordered syntax (page_order and groups), ranges, open-ended and negative indices, and comma lists.

Many actions act on a subset of a document’s pages. You describe that subset with a compact range syntax: comma-separated 1-based page numbers and ranges, such as 1..3,5. The same numbers and ranges appear across every action, but they are read with one of two meanings — as a set or as an ordered list. This page is the single reference for both; every action with a page field links here.

Two kinds of selection

  • A set field (pages) answers which pages. Order and duplicates are ignored, and the selected pages are always processed in document order.
  • An ordered field (page_order, and each group in groups) answers in what sequence. Order and repeats are meaningful — pages come out exactly as written.

The syntax for expressing a range is identical in both. The difference is only in how the result is interpreted.

Set selection — the pages field

A pages field is a comma-separated list of 1-based page numbers and ranges:

  • A single page, such as 5.
  • A range, such as 2..6 (pages 2 through 6).
  • An open-ended range: 8.. is page 8 to the last page, and ..5 is the first page through page 5.
  • A negative index counts from the end: -1 is the last page, -2 the second to last. Ranges accept them too, so -3..-1 is the last three pages.

A pages field is treated as a set: order and duplicates are ignored, and the pages are always processed in document order. Leaving it empty selects every page.

Pattern Selects
(omit) Every page
1 The first page only
2..6 Pages 2 through 6
1..3,5 Pages 1, 2, 3, and 5
8.. Page 8 through the last page
..5 The first page through page 5
..-2 The first page through the second-to-last
-1 The last page
-3..-1 The last three pages

Because a set is order-free, 5,1,2..3 and 1,2,3,5 select exactly the same pages, and both are applied in document order. Some actions add a rule of their own — for example, Remove pages must leave at least one page behind, so a selection that would remove every page is rejected.

Ordered selection — page_order and groups

Some inputs are an ordered list rather than a set. They use the same numbers and ranges as above, but here order and duplicates matter: pages come out exactly as listed, a page named twice is emitted twice, and any page left out is dropped. A range may also run backwards, so 10..5 walks from page 10 down to page 5.

  • page_order (used by reorder) is a single ordered list. 3,1,2 puts page 3 first, then 1, then 2. Because omitted pages are dropped and repeats are kept, reorder doubles as a combined extract, duplicate, and reorder.
  • groups (used by split into page groups) is several ordered lists separated by ;. Each group becomes one output PDF, and within a group the ordered rules apply. 2..8,29;1 produces two documents: the first with pages 2 through 8 then 29, the second with page 1.

Which field each action uses

Field Semantics Actions
pages Set Add text watermark, Add image watermark, Extract pages, Remove pages, Rotate pages
page_order Ordered Reorder pages
groups Ordered, per group Split into page groups

Reach for a set field when the outcome is the same regardless of the sequence you write — stamping a watermark on pages 2, 4, and 6. Reach for an ordered field when the sequence is the outcome — rearranging or repeating pages.

Rules that apply everywhere

  • Page numbers are 1-based. There is no page 0.
  • Negative indices and open-ended ranges work in both set and ordered fields.
  • A selection that references a page beyond the document — such as 12 in a ten-page file — is rejected with a 400. See Errors.