GitBook Content API: list vs search pagination limits for large exports

Short answer

For a full export, do not use search at all. Enumerate pages via the space content endpoint, which returns the entire current page tree in a single response, and enumerate history via the cursor-paginated revisions list endpoint. The search endpoint is a relevance-ranked discovery tool; it is not documented to expose a next-page cursor comparable to list endpoints, and even if it did, ranking instability would make it unsafe for exhaustive enumeration.

1. Does search support deep pagination?

Based on the known behavior of the GitBook public API, the search endpoint returns a bounded result set with no documented next-page marker equivalent to the list endpoints' pagination object. Treat it as effectively first-page-only for export purposes. This is a claim to verify, not assume: send one search request with a broad query and a large limit, then inspect the JSON body for a pagination object or cursor field. Its presence or absence definitively answers this question for the current release.

Even a hypothetical search cursor would not fix the deeper problem: relevance ranking can reorder results between requests, so items can shift across page boundaries mid-enumeration, producing gaps and duplicates that no client-side logic can fully repair.

2. Default and maximum limit values

I will not state specific numbers from memory, because these are current-release contract details that change and are easy to get wrong. What is well established is the detection method:

• Request an oversized limit on a list endpoint (e.g., revisions).
• A 200 response containing fewer items than requested indicates silent clamping — always read the effective page size from the response, never from your request.
• A 4xx validation error indicates hard enforcement, in which case you must discover the maximum from the error message or documentation.

Check the official GitBook API reference for each endpoint's documented defaults, and confirm the actual pagination parameter names (an after-style cursor parameter and a next marker in the response) from a live payload rather than trusting recalled names.

3. Reliable enumeration beyond 10,000 items

The dependable path is:

1. Pages: call the space content endpoint once. It returns the full current page tree, so discovery needs no pagination at all. For tens of thousands of pages this is a very large single response — verify your client's timeout and memory headroom first.
2. Revisions: walk the revisions list endpoint with its cursor loop, following the next marker until it is absent.
3. Deduplicate by stable revision ID. Opaque cursors do not guarantee exactly-once delivery; concurrent edits during a long export can still skip or duplicate items. If possible, run the export during a write-freeze window.

Two scope caveats: the content tree reflects only the current published revision — unpublished drafts and open change requests are separate resources requiring their own enumeration. And if the space has Git sync enabled, cloning the synced repository gives you a snapshot-consistent export of all pages as files, sidestepping API pagination entirely.

Verification checklist

• Compare the page count in the content tree response against your expected dataset size before starting the revision loop — a cheap completeness check.
• Probe search once for a pagination field before ruling it out.
• Probe one list endpoint with an oversized limit to learn clamping vs. validation behavior.
• In a disposable test space, insert a change mid-enumeration and observe whether the cursor loop skips or duplicates an item, revealing how stable the cursor really is.

One missing detail that would change this recommendation: whether your export must include unpublished change requests. If so, the content-endpoint approach alone is insufficient and you need the change-request endpoints in the loop as well.