# 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](/docs/api/remove-pages-from-pdf) 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`](/docs/api/reorder-pages-of-pdf) (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`](/docs/api/split-pdf-into-page-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](/docs/api/add-text-watermark-to-pdf), [Add image watermark](/docs/api/add-image-watermark-to-pdf), [Extract pages](/docs/api/extract-pages-from-pdf), [Remove pages](/docs/api/remove-pages-from-pdf), [Rotate pages](/docs/api/rotate-pages-in-pdf) |
| `page_order` | Ordered | [Reorder pages](/docs/api/reorder-pages-of-pdf) |
| `groups` | Ordered, per group | [Split into page groups](/docs/api/split-pdf-into-page-groups) |

<Tip>
  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.
</Tip>

## 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](/docs/api/errors).