Rate Limiting on the Graph API

Rate limiting defines limits on how many API calls can be made within a specified time period. Rate limits are imposed on every app.

Apps that excessively or persistently exceed their rate limits may be disabled.

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 four major types of rate limits that can be encountered by your app:

Visit our blog post to learn more about the Rate Limiting tool in the app dashboard.

Ad Account Level Rate Limiting

Ad Account level rate limiting is part of the Marketing API rate limiting logic which is separate from the Graph API rate limitations. If you make a Marketing API call, it won't be calculated into the Graph API throttling. Visit the Marketing API rate limiting documentation for more information.

All Marketing API calls from an app made after a rate limit is exceeded are throttled and will fail with Error code 17, error_subcode=2446079. Calls will start to succeed again when usage over the past hour falls back below the limit. Rate limiting occurs in real time on a given time range.

Rate Limit Dashboard

Click View Details in the Ad Account Level Rate Limit card on the app dashboard to view the current percentage of the limit used and time to reset usage. Click the chevron of each account to view the the average activity for the past 7 days. Hover over any point on the graph to see more details about usage for that particular moment. Because usage depends on call volume, this graph may not show a full 7 days. Apps with a higher volume of calls will show more days.

Limits

Rate limiting is in real time at the ad account level over a given time range. Each Marketing API call is assigned a score. Your score is the sum of your API calls. We enforce a maximum score, and when you reach it, we throw a throttling error.

Note: Updates are between 10 to 100 times more resource intensive than creates.

Recommendations

  • Switch to the other ad accounts and come back to this account later.
  • It is better to create a new ad than to change the existing ones.

Rate Limiting Header

All responses to calls made to the Marketing API include an x-ad-account-usage HTTP header. This header contains the current percentage of usage for your ad account.

The rate limiting header is a JSON-formatted string. The following example shows an ad account at 9.67% of it's limit.

x-ad-account-usage: {"acc_id_util_pct":9.67}

When the percent values exceed 100 the ad account will be rate limited.

Application-Level Rate Limiting

These limits apply to calls made using any access token other than a page access token.

All API calls from an app made after a rate limit is exceeded are throttled and will fail with Error code = 4, CodedException. Calls will start to succeed again when the usage over the past hour falls back below the limit. Limits are calculated on a rolling one-hour window, and current utilization percentages can be seen on your app dashboard.

Rate Limit Dashboard

Click View Details in the Application Level Rate Limit card on the app dashboard to view the current percentage of the limit used and the average activity for the past 7 days. Hover over any point on the graph to see more details about usage for that particular moment. Because usage depends on call volume, this graph may not show a full 7 days. Apps with a higher volume of calls will show more days..

Limits

The total number of calls your app can make per hour is 200 times the number of users. This isn't a per-user limit; any individual user can make more than 200 calls per hour, as long as the total for all users does not exceed the app maximum. For example, if your app has 100 users, the app can make 20,000 calls per hour. But your top ten most engaged users could make 19,000 of those calls.

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

The number of users for your app is calculated using the number of daily active users and today's new logins. In cases where there are slow periods of daily usage, the weekly active or even monthly active users are used to calculate the number of users for your app. Apps with high daily engagement will have higher rate limits than apps with low daily engagement, regardless of the actual number of app installs.

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.
  • We also throttle calls based on CPU time used and total time. Endpoints that require a lot of processing may cause your app to hit these limits, despite being below the call-volume limit. Apps rarely hit CPU time and total time limits, except for specialized endpoints. Information about endpoints that are using a lot of CPU time or total time can be seen in the historical graph, if available.

Recommendations

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

All responses to calls made to the Graph API include 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 in the rate limiting graphs. 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.

All API calls from an app made after a rate limit is exceeded are throttled and will fail with `error code 32`. Learn more about Page level rate limiting.

Rate Limit Dashboard

Click View Details in the Page-Level Rate Limit card on the app dashboard to view the current percentage of the limit used. Click the chevron of each Page to view the the average activity for the past 7 days as well as which endpoints are most active. Hover over any point on the graph to see more details about usage for that particular moment. Because usage depends on call volume, this graph may not show a full 7 days. Apps with a higher volume of calls will show more days.

Limits

Rate limits are imposed on each page rather than the app. 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.

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.

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

The number of calls to your page is calculated as the estimated number of calls using your page access token per day. Pages with a larger number of calls per day may have more accurate rate limiting than pages with a smaller number of calls per day. Pages with a very small number of calls per day may have rate limit issues.

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 for more information on the Marketing API.
  • Page Rate Limiting is shared by all apps managing the same page. Please see the dashboard details for the per page usage portion of your app versus all the other apps.

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.

User-Level Rate Limiting

These limits apply to calls made using user access tokens.

All API calls from an app made after a rate limit is exceeded are throttled and will fail with Error code 17. Rate limiting occurs when a specific user account is making too many calls to the API. This can include user calls made over many apps and not just yours. Calls will start to succeed again when the usage over the past hour falls back below the limit. Limits are calculated on a rolling one-hour window, and current utilization percentages can be seen on your app dashboard.

When a user is rate limited, API calls from the user are throttled.

Rate Limit Dashboard

For each user whose access token is used by your app to make calls, the app dashboard gives you information about usage and the rate limits affecting your app.

The User-Level Rate Limit card on your app's dashboard landing page shows the current percentage of the limit used.

Limits

There is nothing you can do to prevent user rate limiting. The user is making too many calls (possibly through other apps) and hence getting rate limited. If this is happening for a lot of users of an app, then it is most likely the API calls made through that app causing this. In this case, you should reduce their calls or spread them more evenly.

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

Account-level throttling

Not applicable

17

Page-level throttling

4800 calls/person/24-hours

32

Custom-level throttling

Not applicable

613


I'm seeing Error Code 613, what do I do?

If your error response contains error_subcode 1996, Facebook has noticed inconsistent behavior in the API request volume of your app. If you have made any recent changes that affect the number of API requests, you may be encountering this error.

If you do not see the subcode, your app is exceeding a custom rate limit. Please contact your Partner Manager for help resolving this issue.


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.