Rate limiting

Rate limiting controls how many API requests your app can make to Jira Cloud within a given time period. This ensures platform stability, fair resource allocation, and a reliable experience for all users.

Why rate limiting matters

Without rate limits, a single app could consume excessive resources, slowing down the platform for everyone. Rate limiting protects against:

• Service degradation: Prevents one app from overwhelming shared infrastructure.
• Resource fairness: Ensures all apps get equitable access to API capacity.
• System stability: Guards against accidental or malicious traffic spikes.

If your app exceeds its rate limit, Jira returns an HTTP 429 Too Many Requests response. Your app should handle this gracefully by pausing requests and retrying after the specified delay.

Points-based rate limiting

Jira Cloud uses a points-based model to measure API usage. Instead of simply counting requests, each API call consumes points based on the work it performs—such as the amount of data returned or the complexity of the operation.

This approach offers several benefits:

• Fairer limits: Heavy operations consume more quota than simple ones.
• Predictable usage: You can estimate your quota consumption based on your API patterns.
• Tiered quotas: Most apps share a global hourly quota. Apps with sustained high usage may qualify for per-tenant quotas after review.
• Consistent model: The same points system applies to both REST and GraphQL APIs.

How points work

Points are calculated based on the type of API request and the objects affected. Each request starts with a base cost of 1 point, and additional points are added for each object involved. Write requests are charged only the base cost, with no additional points.

This straightforward model applies to both REST and GraphQL APIs. This table provides the object costs break down:

Note: We plan to expand our catalog in the future to provide more detail on object costs. Most requests are dominated by object costs.

Rate limit quotas by tiers

All quotas are measured in points per hour and reset at the top of each UTC hour.

Understanding the tier system

Your app's hourly quota depends on two factors:

• Rate limit tier: Global Pool (default) or Per-Tenant Pool.
• Customer edition: In the Per-Tenant Pool, Free, Standard, Premium, or Enterprise and the number of users.

Tier 1 – Global Pool (default)

Your app shares a single 65,000 point hourly quota across all tenants. This is the default tier for all apps. Most apps operate comfortably within the Global Pool.

Tier 2 – Per-Tenant Pool

Your app receives a separate hourly quota for each tenant, with limits varying by their edition. Only apps with exceptionally high or concentrated usage patterns may be assigned to the Per-Tenant Pool after review.

How Tier 2 limits are calculated (for apps assigned to this tier): For apps operating in the Per-Tenant Pool, each tenant receives a quota based on their edition and user count:

• Standard: 100,000 base + 10 points per user per hour
• Premium: 130,000 base + 20 points per user per hour
• Enterprise: 150,000 base + 30 points per user per hour

Per-tenant rate limits are capped at 500,000 points per hour for Standard, Premium, and Enterprise editions.

Quota calculation examples

Standard tenant with 2,000 users:
100,000 + (10 × 2,000) = 120,000 → 120,000 points/hour

Enterprise tenant with 15,000 users:
150,000 + (30 × 15,000) = 600,000 → 500,000 points/hour (capped)

API operation examples

The following examples show how points are calculated for common Jira REST API operations.

Read operations

Scenario:
Amy is building an integration that syncs Jira issues to an external dashboard, she fetches a single issue:

1
2
GET /rest/api/3/issue/ABC-123 

Cost calculation

1
2
 1 (base) + 1 Issue = 2 points

Later, Amy’s integration fetches all members of a group using the group membership API. Since each user object costs 2 points, the request is more expensive:

1
2
GET /rest/api/3/group/member?groupname=my-group 

Cost calculation

1
2
 1 (base) + 8 users = 17 points (1 + 8 × 2)`

Write operations

Scenario:
Alex is automating issue creation for a support workflow. All write operations cost 1 point regardless of object type:

1
2
POST /rest/api/3/issue → 1 point

If Alex's script creates 50 issues in a batch, that's 50 points consumed from the quota (50 issues × 1 point each).

Burst rate limits

Quota and burst rate limits are enforced independently. Burst limits are evaluated over short time windows (typically seconds) to prevent traffic spikes, while quota limits are evaluated hourly. Even if you remain within your hourly quota, a rapid surge of requests can trigger burst limiting. Burst limits reset quickly, allowing normal operations to resume within seconds. Certain high-impact endpoints (Permissions, Search, Admin operations) enforce additional burst protections for system stability.

Per-issue rate limiting on write operations

In addition to the standard rate limiting mechanisms, Jira implements per-issue rate limiting on write operations to protect against scenarios where a single issue receives an excessive number of updates in a short time frame. This rate limiting is designed to prevent system instability and to provide reliable service for all customers.

What is per-issue rate limiting?

Per-issue rate limiting restricts the number of write operations (create, update, delete) that can be performed on a single Jira issue within specific time windows.

Thresholds

Per-issue rate limiting operates with two time windows:

• Short window: 20 write operations per 2 seconds
• Long window: 100 write operations per 30 seconds

Rate limit response

When per-issue rate limiting is triggered, you'll receive:

• HTTP status code: 429 Too Many Requests
• RateLimit-Reason header: jira-per-issue-on-write

Best practices for handling per-issue rate limiting

1. Implement exponential backoff and distribute write operations over time: When you receive a 429 response with RateLimit-Reason: jira-per-issue-on-write, use exponential backoff with jitter before retrying the write operation. You do not need to delay writes for other issues—it is only needed for the specific issue that triggered the rate limit.

2. Batch operations when possible: Use bulk operations or combine multiple changes into a single request to reduce the number of operations counted against per-issue rate limits:

   • Single-issue bulk operations: APIs like bulk delete worklogs or bulk move worklogs count as a single operation against the per-issue limit, even when processing multiple items for one issue.
   • Multi-issue bulk operations: The Issue bulk operations APIs are excluded from per-issue rate limiting as APIs designed for multiple issues updates.
   • Combined field updates: Instead of updating issue fields through multiple API calls, combine changes into a single update request.

3. Design for distributed operations: In distributed systems, multiple automated processes or users may simultaneously modify the same issue. Implement resilient patterns to handle concurrent operations gracefully:

   • Implement retry logic with exponential backoff when operations fail due to rate limiting.
   • Track and manage your application's rate limit budget to optimize performance.
   • Design your application to handle temporary failures and continue operating.

Rate-limiting enforcement, responses, and best practices

Atlassian enforces API rate limits by tracking your usage in hourly intervals, measured in points. Each app or token has a set quota of points per hour, which resets at the top of each hour (UTC). If your usage exceeds the quota, further requests are denied with an HTTP 429 response until the next window begins. There is no partial throttling once the quota is reached, all requests are blocked until reset.

Key points:

• Quotas are measured in points per hour and reset at the start of each UTC hour.

• There is no carry-over between hours; unused quota does not accumulate.

• When the quota is reached, all further requests are denied until the next reset.

• This model provides predictable enforcement and makes it easy for developers to monitor usage and reset times.

Apps can detect rate limits by checking for HTTP 429 responses. Any REST API can return a rate limit response.

Rate limit responses

Rate limit detection

Apps can detect rate limits by checking if the HTTP response status code is 429. Any REST API can return a rate limit response.

Rate limit related headers

Example 429 response

1
2
HTTP/1.1 429 Too Many Requests
Retry-After: 1847
X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-10-08T15:00:00Z
RateLimit-Reason: jira-quota-global-based

Retrying and backoff strategies

• Retry only when appropriate:
  Only retry if the API is idempotent and the response includes a Retry-After header
• Exponential backoff with jitter:
  Use exponential backoff and add random jitter to delays to avoid the thundering herd problem.
• Double the delay after each 429:
  Increase the delay after each successive 429, up to a maximum.
• Monitor and tune:
  Adjust retry thresholds, delays, and maximum retries based on your app’s needs and observed behavior.

Pseudocode for retry logic:

1
2
let maxRetries = 4;
let lastRetryDelayMillis = 5000;
let maxRetryDelayMillis = 30000;
let jitterMultiplierRange = [0.7, 1.3];
let response = await fetch(...);
if (response is OK) {
  handleSuccess(...);
} else {
  let retryDelayMillis = -1;
  if (hasHeader('Retry-After')) {
    retryDelayMillis = 1000 * headerValue('Retry-After'); 
  } else if (statusCode == 429) {
    retryDelayMillis = min(2 * lastRetryDelayMillis, maxRetryDelayMillis);
  }
  if (retryDelayMillis > 0 && retryCount < maxRetries) {
    retryDelayMillis += retryDelayMillis * randomInRange(jitterMultiplierRange);
    delay(retryDelayMillis);
    retryCount++;
    retryRequest(...);
  } else {
    handleFailure(...);
  }
}

The following articles provide useful insights and techniques related to retry and backoff processing:

• Exponential backoff article in Wikipedia
• Error retries and exponential backoff in AWS

App request scheduling

Efficiently scheduling your app’s API requests is essential for staying within your hourly points quota and ensuring reliable performance for your users. Whether you’re running batch jobs, automations, or large data migrations, thoughtful scheduling helps you avoid rate limit errors and make the most of your available quota.

Best practices for scheduling API requests:

• Distribute requests over time: Spread your requests evenly throughout the hour, rather than sending large bursts at predictable intervals.

• Apply random jitter: Add a random delay ("jitter") to scheduled jobs to avoid many apps hitting the API at the same time.

• Coordinate across threads and nodes: Share rate limit status between threads or servers to prevent accidental quota exhaustion.

• Avoid using concurrency to bypass limits: Excessive parallelism can lead to more frequent 429 responses and degraded performance.

• Schedule heavy jobs during off-peak hours: For large, ad-hoc operations, consider running them during periods of lower user activity.

• Example: Instead of scheduling all batch jobs to run at 00:00 UTC, stagger them with random delays or intervals (e.g., every 5–10 minutes) to smooth out traffic and reduce the risk of hitting your hourly quota early in the window.

Optimizing for efficiency and quota usage

• Request only the data you need: Limit fields, use pagination, and avoid fetching unnecessary objects.

• Cache stable responses: Use ETags and conditional headers to avoid re-fetching unchanged data.

• Use bulk operations thoughtfully: Bulk operations may consume more points per request, but can reduce the number of HTTP calls and improve efficiency. Always check the point cost and consider whether batching is optimal for your use case.

• Leverage webhooks and context parameters: Use webhooks for updates and context parameters to minimize the number of API requests.

Testing and compliance

• Do not perform rate limit testing against Atlassian cloud tenants, as this may impact customers.
• Follow the Atlassian Acceptable Use Policy to avoid overwhelming Atlassian infrastructure.

Additional resources

• Atlassian Acceptable Use Policy, January 24, 2020.
• Efficient Use of Atlassian Cloud REST APIs, Raimonds Simanovskis, Founder and CEO, eazyBI, 2019.
• Exponential Backoff and Jitter, Marc Brooker, 2015.

These rate limits are designed to provide generous capacity for our developer community. However, to ensure platform stability and protect against abuse, these limits and the policies governing them are subject to change. We will strive to provide notice of significant changes, but we reserve the right to make adjustments as needed to protect the service.

FAQs