Bitbucket REST API commits pagination: choosing page size without total count

Question

When using the Bitbucket Cloud REST API /2.0/repositories/{workspace}/{repo_slug}/commits to iterate through a repository’s commit history, the client must rely on the pagelen and page (or start) parameters to bound each response. The API caps pagelen at 100 and defaults to 25, but it does not return a total commit count, so the caller cannot know in advance how many pages exist or when the final page has been reached.
Given the workspace‑level rate limit of 1 000 requests per hour and the desire to minimize the number of round‑trips while staying safely under that limit, the optimal page size is unclear when the total number of commits is unknown.
What pagelen setting provides the best trade‑off between request count and rate‑limit safety for an unknown‑size commit set? How should a client determine that it has processed the last page without a total count indicator? Should the client adjust pagelen dynamically based on the next link or rate‑limit response headers?

Tasadduq Burney · Answer

To minimize round-trips while staying under the 1,000 request per hour rate limit, the optimal page size is the maximum allowed pagelen=100.Because the Bitbucket Cloud REST API does not provide a total commit count, the most efficient strategy to exhaust the history is to maximize the data retrieved in each request. Since the API caps pagelen at 100, using this value reduces the total number of network calls required to traverse the entire commit history.

How to detect the last page
In the absence of a total count, the client must rely on the response structure to determine termination. The Bitbucket 2.0 API uses a cursor-based pagination model. To identify the final page, you should:

Check for the next key at the root level of the JSON response.
  If the next key exists, it contains the URL for the next set of results.
  If the next key is absent or null, you have reached the end of the commit history.

Dynamic adjustment vs. Static sizing
While it is tempting to adjust pagelen dynamically based on rate-limit headers, it is generally unnecessary for this specific API for several reasons:

Hard Caps: The API enforces a hard limit of 100. Setting a higher value will not yield more results per request.
  Request Overhead: The rate limit is per-request, not per byte or item. Fetching 100 commits in one request is 4x more "cheaper" for your rate limit than fetching 25 commits in four requests.
  Consistency: A static pagelen=100 provides predictable performance and simplifies the logic required to handle the next link-header navigation.

Verification Strategy
To ensure your implementation handles the pagination correctly, use the following logic flow:
GET https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/commits?pagelen=100

Response handling:
1. Process the 'values' array.
2. If response.next exists:
   Repeat using the URL found in response.next.
3. Else:
   Stop iteration.
Note: This assumes you are using the Bitbucket Cloud API v2.0. Older v1.0 endpoints use different parameter schemes (like offset) and are deprecated.

Bitbucket REST API commits pagination: choosing page size without total count

1 answer

To minimize round-trips while staying under the 1,000 request per hour rate limit, the optimal page size is the maximum allowed `pagelen=100.`

How to detect the last page

Dynamic adjustment vs. Static sizing

Verification Strategy

Your perspective belongs here.

0 question comments