Rate limiting

Rate limiting controls how many API requests your app can make to Confluence 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, Confluence 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

Confluence 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 Confluence REST API operations.

Read operations

Simple page fetch

Sarah is building a documentation sync tool. She fetches a single Confluence page:

1
2
GET /wiki/rest/api/content/123456

Cost calculation:

1
2
1 (base) + 1 (Page object) = 2 points

Space details

Sarah retrieves details about a specific space:

1
2
GET /wiki/rest/api/space/DOCS

Cost calculation:

1
2
1 (base) + 1 (Space object) = 2 points

User lookup

Marcus is building a permissions audit tool and fetches user information:

1
2
GET /wiki/rest/api/user?accountId=557058:12345678-abcd-1234

Cost calculation:

1
2
1 (base) + 2 (User object) = 3 points

Write operations

Creating a new page

Alex is automating page creation for a knowledge base workflow:

1
2
POST /wiki/rest/api/content
{
  "type": "page",
  "title": "Q4 Planning",
  "space": {"key": "TEAM"},
  "body": {
    "storage": {
      "value": "<p>Content here</p>"
    }
  }
}

Cost calculation:

1
2
1 point

Updating an existing page

Alex updates the page with new content:

1
2
PUT /wiki/rest/api/content/123456
{
  "version": {"number": 2},
  "title": "Q4 Planning - Updated",
  "body": {
    "storage": {
      "value": "<p>New content</p>"
    }
  }
}

Cost calculation:

1
2
1 point

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.

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.
• Each request must stay within the maximum allowed cost per request.
• 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: 40000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-10-08T15:00:00Z
RateLimit-Reason: confluence-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