API request limits

Resource/rate limits and paging

Resource and rate limits, and the default and maximum sizes of paged data are not considered part of the API and are subject to change (possibly dynamically).

How calls are measured

Tracking the number of calls is measured based on if they are authenticated or unauthenticated calls as follows: 

  • Unauthenticated calls: measured against a specific IP address.

  • Authenticated calls: measured against the user ID.

Rate limits are divided into a one-hour rolling window for both authenticated and unauthenticated requests, which means that for every minute that passes, you will be provided that time to run new requests but the total you can run consecutively over an hour is 1,000. 

Anonymous Request limits

Anonymous requests are subject to a strict rate limit of 60 requests per hour across all API resources. If you need access to a larger request pool, logging in is required.

Authenticated Request limits

The following table defines our API request limits for authenticated requests:

Limit type

limit

Git Operations (both HTTPS and SSH requests)

60,000 requests per hour

Access to raw files                

Raw file requests: the number of times a file is actively downloaded, including files in the download section of the site.

This is not a limit on actions such as:

  • Pushing or pulling commits

  • Running a fetch command to get recent changes

  • Pushing or pulling a branch (unless that branch contains more than 1000 new files)

5,000 requests per hour                                        

Archive files: .zip, .gz, and other compressed archives of your repository.

5,000 files per hour

Access to repository data

Scaled rate limits apply

Any access to /2.0/repositories/* such as:

  • List a user or team's repositories (/2.0/repositories/{workspace})

  • List all repositories on Bitbucket (/2.0/repositories)

  • List a repository's commits (/2.0/repositories/{workspace}/{slug}/commits)

1,000 - 10,000 per hour

 

Access to webhook data

Limited to the following actions across a workspace or repositories:

  • List all webhooks

  • Add webhooks

  • Remove webhooks

1,000 per hour

Access to application properties

Any access to application properties, such as:

  • Get commit / repository / pull request application properties

  • Update commit / repository / pull request application properties

  • Delete commit / repository / pull request application properties

2,000 per hour

Sending invitations

  • Issue an invitation to a group (/1.0/users/{accountname}/invitations)

  • Invite a user to a repository (/1.0/invitations/{accountname}/{repo_slug})

100 requests per minute

Scaled rate limits

Scaled rate limits help your organization continue to use Bitbucket REST APIs in a timely and consistent manner as your organization continues to grow.

Requirements:

  • Standard or Premium plan

  • 100 or more paid users in the workspace

  • Must use workspace, project, repository access tokens for authentication or make requests through programmatic access via a Forge app. Note: For Forge programmatic access, the scaled rate limits are available to API requests using the asApp app user.

For users who meet the above requirements, an additional 10 API requests per hour per paid user are available.

This rate limit increase is capped at a maximum of 10,000 requests per hour

How the scaled rate limits work

The scaled rate limits are applied to a group of endpoints that can handle the increased load from the API requests. This group of API endpoints is in a collective known as the api resource group. Note: The endpoints within this collective are subject to change at any time.

Example of how scaled rate limits work with access tokens and Forge asApp app user

Consider a request being made by a repository access token in repository ‘repo1’ which is in ‘workspace1’. The workspace (workspace1) has a plan paying for 500 users (seats), so the access token will receive a scaled rate limit of 5,000 requests per hour.

  • The default rate limit is 1,000 requests per hour.

  • For each user beyond the initial 100, the scaled rate limits are enforced.

  • A total of 400 seats are factored into the calculation for the scaled rate limits.

  • The overall calculation for total requests is: 1,000 + (500 - 100) * 10 = 5,000

Rate limit response headers

Additional response headers will be returned from endpoints that are applicable to the scaled rate limits for requests made by access tokens and Forge asApp requests. These response headers are returned to help requesters understand their rate limit usage. The additional response headers that will be returned are the following:

  • X-RateLimit-Limit: Represents the total number of requests permitted per hour. Note, this is not the number of remaining possible requests

  • X-RateLimit-Resource: Identifies the API endpoint resource group receiving scaled rate limits

  • X-RateLimit-NearLimit: A boolean value indicating whether less than 20% of the requests remain

For example, for a workspace with 500 paid seats and with less than 20% of requests remaining, the following response headers will be returned when an API request is made to an endpoint with scaled rate limits applied.

Response Header

Value

X-RateLimit-Limit

5000

X-RateLimit-Resource

“api”

X-RateLimit-NearLimit

“true”

 

Still need help?

The Atlassian Community is here for you.