Confluence REST API content pagination: totalSize and willPaginate reliability for large spaces

1. totalSize – Is it a true count?

The totalSize field is the result of the query at the instant the request is made. Atlassian’s Data Center implementation caps this value at the system property confluence.query.max-results (default 10,000). When a space contains more items than this cap, totalSize will equal the cap value, not the real number of pages. Therefore, totalSize is not a reliable indicator of the full dataset size in large spaces unless you know the property has been increased.

2. When to stop paginating?

Because totalSize can be truncated, using start >= totalSize as a termination guard is unsafe. The most robust approach is:

• Keep fetching until the API response contains willPaginate: false.
• Or, stop when the returned results array is empty.

Both conditions reflect the API’s current state and are unaffected by the confluence.query.max-results cap.

3. What happens if content changes while you paginate?

Offset‑based pagination (start/limit) is sensitive to concurrent inserts or deletes. A new page inserted before the current offset will shift every subsequent item down one position, causing duplicates or missed items. Deletions have the opposite effect. The API does not provide a cursor or immutable ordering to shield against this drift.

4. Is there a stable‑ordering or cursor option?

The standard /rest/api/content endpoint does not expose a cursor. You can supply a sortBy parameter (e.g., createdDate, lastModified) to impose a deterministic order, but the offset still moves if the underlying set changes. For truly stable iteration you would need to snapshot the set first (e.g., export a list of IDs) or use a custom query that locks the result set.

5. Practical recommendation for an export job

1. Determine the current confluence.query.max-results value. If it is 10,000 and you expect more pages, plan for capped totalSize.
2. Paginate using limit (e.g., 1,000) and increment start by that amount.
3. Continue until willPaginate becomes false or the results array is empty.
4. If the space is highly dynamic, consider:
   • Running the export in a maintenance window when writes are paused.
   • Pre‑fetching all content IDs with a single query and iterating over that ID list.
   • Adding a sortBy clause to reduce drift, with the understanding that it does not eliminate duplicates.

6. What we still need to know

To fine‑tune the strategy, it would help to know the current value of confluence.query.max-results in your instance. If you have increased that property, totalSize may be accurate for your space.