Breadcrumbs

REST Query Pagination

Many REST APIs return large result sets one page at a time — a single request only gives you the first slice (for example, the Jira REST API returns at most 100 issues per call). PocketQuery can follow that paging for you and merge every page into one result, so your query, Converter and Template see the complete dataset with more rows instead of just the first page.

Pagination is configured per REST query. Open a REST query and use the Pagination field, located between the query URL and the Description.

Modes

  • Off — no pagination. The query issues a single request and returns whatever that one response contains (the default).

  • Automatic — PocketQuery inspects the first response and detects common paging conventions on its own: a startAt/offset parameter, a page number, a cursor/token in the body, a next-page URL (e.g. _links.next), or an RFC 5988 Link header. This is the easiest option and works with most well-known APIs, including the Jira REST API.

  • Manual — you specify exactly how the API pages. Use this when detection cannot decide, or when you want full control.

Manual settings

When you choose Manual, first pick the Pagination type, then fill in the fields it needs:

Pagination type

How the next page is requested

Key fields

Start offset in a parameter

A growing offset in a request parameter (e.g. Jira's startAt)

Offset parameter (default startAt)

Page number in a parameter

An increasing page number (e.g. page=1)

Page parameter (default page), First page number (some APIs start at 0)

Token from the response body

A cursor/token read from the response and sent on the next request

Token parameter (default nextPageToken), Token path in the response

Next page URL from the response body

A complete next-page URL contained in the response

Next page URL path (e.g. _links.next)

Next page URL from the Link header

A next-page URL in the RFC 5988 Link header (e.g. GitHub)

(none — read from the header)

Additional fields (available in Manual mode):

  • Results path in the response — the array to merge, e.g. issues or data.items. Leave empty for a root-level array or a common field name.

  • Page size parameter / Page size — the parameter that sets how many records per page (e.g. maxResults or limit) and its value. Leave the parameter empty to let the API decide. Maximum page size: 1000.

  • Total count path, Last page flag path, Has more pages flag path — optional response fields PocketQuery uses to know when to stop (e.g. total, isLast, hasMore).

Safety limits

These apply to both Automatic and Manual mode:

  • Maximum pages — an upper bound on how many pages PocketQuery will fetch (default 50, maximum 100). This prevents a misconfigured query from making an unbounded number of requests.

  • Allow incomplete results — when unchecked (the default), reaching a limit fails the query so you notice the result is truncated. Check it to return the partial result that was collected so far instead.

Example: fetching all Jira issues

A REST query against the Jira REST API (which caps each response at 100 issues):

  1. Set Pagination to Automatic and run the query. PocketQuery detects Jira's startAt/maxResults paging and merges all pages — you get every issue, not just the first 100.

  2. If you prefer to be explicit, set Pagination to Manual, choose Start offset in a parameter, and set:

    • Offset parameter: startAt

    • Page size parameter: maxResults, Page size: 100

    • Results path in the response: issues

  3. Raise Maximum pages if your result spans more than 50 pages, and decide whether an incomplete result should fail the query or be returned as-is.