Confluence REST API content pagination: limit parameter clamped or rejected above default 25

Question

I am working with the Confluence REST API endpoint GET /rest/api/content, which paginates results using the start and limit parameters. The documented default page size is 25, and I understand the maximum can be tuned via the confluence.rest.results.max system property in confluence.cfg.xml.

What I cannot pin down is the exact behavior when a request specifies a limit above the configured maximum. Some references suggest the API returns a 400 error, while others indicate the value is silently clamped to the maximum, and the behavior appears to differ across Confluence versions. This matters for client code that must decide whether to retry with a smaller limit or treat the response as an error.

There is also a secondary concern: in a clustered (Data Center) deployment, pagination over large result sets may return duplicate or missing entries if the index is out of sync between nodes, and I am unsure how to detect that condition reliably.

Assuming a recent Confluence Data Center version:

For a given version, does exceeding confluence.rest.results.max produce a 400 response or silent clamping, and where is this documented?
After changing the property and restarting, which response fields (e.g., size, limit, _links.next) confirm the new maximum is in effect?
Is there a supported way to detect duplicate pages caused by index lag during pagination in a cluster?

Wasi · Answer

Answer to the core questions

Limit exceeding the configured maximum
    In recent Confluence Data Center releases (7.13+ and 8.x), the REST API does **not** return a 400 error when the limit query parameter is larger than confluence.rest.results.max. The request is silently clamped to the configured maximum. The response JSON contains a limit field that reflects the clamped value, and the size field equals that value (when enough content exists). Earlier Server 7.x versions behaved similarly; older Server 6.x could return 400, but that is largely deprecated. The Atlassian documentation for the v1 REST API mentions “The limit parameter is capped at the value of confluence.rest.results.max”, which is the authoritative source.
  
  Confirming a new maximum after change
    1. Edit confluence.cfg.xml (or use the JVM property) to set confluence.rest.results.max to the desired value, e.g. 200.
    2. Restart the Confluence node.
    3. Run a probe:
    curl -s -u "admin:admin" "https://confluence.example.com/rest/api/content?limit=200" | jq '.limit, .size, ._links.next'
    The limit field should equal 200 and size should be <=200. If you request limit=201, the response limit will still be 200; no error is returned.
    4. Optionally, check the _links.next URL. Its start value should increment by the clamped limit, confirming that pagination respects the new maximum.
  
  Detecting duplicate/missing pages caused by index lag
    There is no official API endpoint that flags “index lag” during pagination. The recommended defensive strategy is:
    
      Collect content IDs from each page.
      Maintain a set of seen IDs; if an ID appears again, you have a duplicate caused by a stale index.
      If you notice gaps (missing IDs) after a full traversal, the index may be out of sync.
    
    For cluster health, use the Confluence admin UI (System → Index → Reindex status) or the /rest/api/index/status endpoint to verify that all nodes report the same index state.

What to ask next
To give the most accurate guidance, please confirm the exact Confluence version you are running. The clamping behavior is consistent from 7.13 onward, but older Server releases may differ.

Confluence REST API content pagination: limit parameter clamped or rejected above default 25

1 answer

Answer to the core questions

What to ask next

Your perspective belongs here.

0 question comments