Rate Limiting on the Graph API

Rate limiting in the Facebook Graph API should be encountered only in rare circumstances. This document describes what those limits are and how to handle them.

There are two major types of rate limits that can be encountered by your app, application-level rate limiting and page-level rate limiting.

Application-Level Rate Limiting

These limits apply to calls made using any access token other than a page access token. Your app will receive error code 4 if you hit these limits.

Rate limit dashboard

View the charts for your app's rate limit activity on your app's app dashboard.

Limits

Rate limits are imposed on each app. The rate limiting tool gives you information about how close your app is to being throttled. Click on any sample to get more detail on the types of utilization.

Your app can make 200 calls per hour per user in aggregate. As an example, if your app has 100 users, this means that your app can make 20,000 calls. This isn't a per-user limit, so one user could make 19,000 of those calls and another could make 1,000. This limit is calculated based on the number of calls made in the previous hour.

When your app is rate limited, all calls for the app are limited, not just ones for a specific user.

The number of users for your app is calculated as the average number of daily active users plus today's new logins.

Caveats:

  • Not all API calls are subject to rate limits so the number of calls you make may not match what you see in the rate limit tool.
  • Facebook also throttles calls based on CPU time used and total time. It is difficult to hit these limits, so it is an extremely rare occurrence. This information is exposed in the detail pane for each sample. Click on the graph in the rate limit tool on your dashboard for details.
  • The Ads Insights API and the Marketing API may use a different set of rate limits. Please see the Marketing API Rate Limiting document at https://developers.facebook.com/docs/marketing-api/api-rate-limiting for more information on the Marketing API.

Recommendations

Rate limiting defines limits on how many API calls can be made within a specified time period. When a rate limit is exceeded, all API calls from an app are throttled and fail for a brief period of time. Once an app is throttled, the caller will get an error for subsequent calls with error code = 4, CodedException. It can take up to an hour for your requests to be accepted again.

To avoid rate limiting:

  • Spread out queries evenly between two time intervals to avoid sending traffic in spikes.
  • Use filters to limit the data response size and avoiding calls that request overlapping data.
  • Use the rate limiting header to dynamically balance your call volume.

Rate limiting header

If your app is making enough calls to be considered for rate limiting by our system, we return an X-App-Usage HTTP header. This header contains the current percentage of usage for your app. This percentage is equal to the usage shown to you on the rate limiting graph. Use this number to dynamically balance your call load to avoid being throttled.

The rate limiting header is a JSON-formatted string in the following form:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

The values for x, y and z are whole numbers representing the percentage used values for each of the metrics. When any of these metrics exceed 100 the app will be rate limited.

Page-Level Rate Limiting

These limits apply to calls made using a page access token. Your app will receive error code 32 if you hit these limits.

The blog post at https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/ provides a detailed explanation of page level rate limiting.

Rate limit dashboard

For each page whose access token is used by your app to make calls, you can view the rate limiting charts for that page.

Limits

Rate limits are imposed on each page rather than the app. The rate limiting tool will give you information about how many apps use that page's access token and how close the page is to being throttled. Click on any sample to get more detail on the types of utilization.

The number of daily engaged people using a page is the unique number of people who have interacted with the page in a 24-hour period. An interaction with a page consists of a click on the page or page content. You can get this value with the Insights API page_engaged_users metric.

The number of engaged users in the previous 24 hours is used to calculate the rate limits for the current 24-hour window.

A total of 4800 calls per daily engaged users can be made on behalf of the page per 24 hours in aggregate. As an example, if the page has 100 daily engaged users, then 480,000 calls can be made on behalf of the page in a 24-hour period. This 24-hour period is a sliding window that is updated every few minutes. The call limit is a per-page limit, so one app could make 400,000 calls and another could make 80,000. If a page is rate limited, only the calls from your app using that page's access token will be limited. This means that your app can still function normally for other calls.

Caveats:

  • Not all API calls are subject to rate limits so the number of calls you make may not match what you see in the rate limit tool.
  • Facebook also throttles calls based on CPU time used and total time. Click on the graph in the rate limit tool on your dashboard for details.
  • The Ads Insights API and the Marketing API may use a different set of rate limits. Please see the Marketing API Rate Limiting document at https://developers.facebook.com/docs/marketing-api/api-rate-limiting for more information on the Marketing API.

Recommendations

Once a page is throttled, the caller will get an error for subsequent calls with error code = 32, CodedException. It can take up to an hour for your requests to that page to be accepted again.

To avoid rate limiting:

  • Spread out queries evenly between two time intervals to avoid sending traffic in spikes.
  • Use filters to limit the data response size and avoiding calls that request overlapping data.
  • Use the rate limiting header to dynamically balance your call volume.

Rate limiting header

If enough calls are being made on behalf of a page to be considered for rate limiting by our system, we return an X-Page-Usage HTTP header. This header contains the current percentage of usage for the page. If you make calls using the access token of a page, you will get the X-Page-Usage value for that page only. This percentage is equal to the usage shown on the rate limiting graph for that page. Use this number to dynamically balance your call load to avoid being throttled.

The rate limiting header is a JSON-formatted string in the following form:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

The values for x, y and z are whole numbers representing the percentage used values for each of the metrics. When any of these metrics exceed 100 the app will be rate limited.

FAQ

What do we consider an API call?

All calls count towards the rate limits, not just individual HTTPS API requests. For example, you can make a single API call and specify multiple ids, but each ID would count as its own API call, even though you are only making one HTTPS API request.

To illustrate this concept, see the examples below:

Example Request(s) Number of API Calls

GET https://graph.facebook.com/photos?id=4
GET https://graph.facebook.com/photos?id=5
GET https://graph.facebook.com/photos?id=6

3

GET https://graph.facebook.com/photos?id=4,5,6

3

In a scenario where you need to traverse multiple objects by ID, we strongly recommend you use the second approach as it will improve performance of your API responses, but it will not improve the number of calls made for the purposes of rate limiting.

You can also use the Batch API to batch your requests, but note that each sub-request is its own API call, or even multiple API calls in the case of specifying many ids.

If you app or page becomes rate limited, API calls that encounter rate limiting errors also count towards your rate limit.

What Errors Will My App See?

Throttling Type At least Error Code

Application-level throttling

200 calls/person/hour

4

Page-level throttling

4800 calls/person/24-hours

32

I'm building a scraper, is there anything else I need to worry about?

If you're building a service that scrapes data, read our scraping terms.