Rate Limiting on the Graph API

Rate limiting defines limits on how many API calls can be made within a specified time period. These 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.

Starting with the Graph API v3.3 release on April 30, 2019, changes have been applied to our rate limiting system for businesses integrating with Facebook Business APIs for Page management (Pages API), ad insights (Ad Insights API) and Instagram (Instagram API) including new headers for the new rate limiting logic. Improvements include:

  • The ad account level has been divided in two, Ads Insights and all remaining Ads API.
  • The Instagram account rate limit is now determined by analyzing the number of impressions on the Instagram account in a 24-hour period. Please note that your rate limit is no longer determined by the number of Users on the app.
  • The Page level rate limit is rate limiting logic for apps owned by a business and use either a Page or system access token. All apps qualifying for Pages API v3.3 now have their own ratio limit quota and do not share it with other apps accessing the same Page.

This is a 90-day breaking change. All apps will be automatically migrated to this new logic on July 30, 2019. Upgrade to v3.3 to apply this new logic.

The major types of rate limiting encountered by your app are:

Learn more about updates to the app dashboard Rate Limiting tool in our blog post.

Ad Account Level Rate Limiting

The Ad Account Level Rate Limiting is composed of two separate rate limits, Ads Insights and All Remaining Ads API.

For Graph API v3.2 and older, apps follow the Marketing API rate limiting logic until July 30, 2019 when all apps will be automatically migrated to the new logic. Upgrade to v3.3 now to apply this new logic.

Ads Insights Level Rate Limiting

Ads Insights rate limiting is part of the Business Use Case rate limiting logic which is separate from the Graph API rate limitations. If you make an Ads Insights call, it is not calculated into the Graph API throttling. Ads Insights rate limiting is determined by analyzing your app access tier, the number of ads in your ad account, and the number of API errors.

Limits

Rate limiting is in real time at the ad account level over a given time range. Each Ads Insights API call is assigned a score. Your score is the sum of your API calls, the CPU time used, and the total time.

Apps rarely hit CPU time and total time limits, except for specialized endpoints. However, endpoints that require a lot of processing may cause your app to hit these limits, despite being below the call volume limit. Information about endpoints that are using a lot of CPU time or total time can be seen in the app dashboard.

Calls fail with error code 80000, error subcode 2446079 if the call counts, total CPU time, or total time reach 100% usage. Calls start to succeed again when the usage rate falls back below the limit.

Rate Limiting Header

All responses to calls made to the Ads Insights API include an x-business-use-case-usage HTTP header. This JSON-formatted string contains your business ID, the percentage of calls made for that particular ad account, the total CPU time, the total time, the type of rate limiting being reported, and the estimated time before you can start making calls again if the account has been throttled.

The following example shows a business account that has been throttled.

x-business-use-case-usage: {
  '{business-id}':  [{
     'call_count':100,       //Percentage of calls made for this business ad account.
     'total_cputime':16,     //Percentage of the total cpu time has been used.
     'total_time': 45,       //Percentage of the total time has been used.
     'type':'ads_insights',                      //Type of rate limit logic being applied.
     'estimated_time_to_regain_access'; 10       //Time in minutes to resume calls.
  }]
}    

The values for call_count, total_time, and total_cputime are whole numbers representing the percentage used for each of the metrics. When any of the call_count, total_cputime, or total_time reach 100 calls are throttled.

Rate Limit Dashboard

In the app dashboard, click Ads Insights v3.3 in the Ad Account-Level Rate Limit card. Then, click View Details to view the current percentage of the limit used and rate limiting data for your top five ad accounts. Click the chevron of each account to view 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.

You can also search for an account not listed using the search box in the upper right corner using the ad account ID.

Recommendations

  • When the limit has been reached stop making API calls. Continuing to make calls will continue to increase your call count which will increase the time before calls will be successful again.
  • Check the x-business-use-case-usage HTTP header to see how close your ad account is to its limit and when you can resume making calls.
  • Verify the error code and API endpoint to confirm the throttling type.
  • Switch to other ad accounts and come back to this account later.
  • It is better to create a new ad than to change existing ones.

All Remaining Ads API

All Ads API calls other than Ads Insights are rate limited using the Marketing API rate limiting logic which is separate from the Graph API rate limitations. If you make a Marketing API call, it is not calculated into the Graph API throttling. Visit the Marketing API rate limiting documentation for more information.

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. All Marketing API calls from an app made after a rate limit is exceeded are throttled and fail with error code 17, error subcode = 2446079. Calls succeed again when the usage rate falls back below the limit.

Rate Limiting Header

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

The following example shows an ad account at 9.67% of its limit.

x-ad-account-usage: {
  'acc_id_util_pct':9.67     //Percentage of calls made for this ad account.
}

When the percent value exceeds 100 the account is rate limited.

Caveats

  • If the business use case rate limit is applied, this ad account level rate limiting is not applied.

Rate Limit Dashboard

In the app dashboard, click All Remaining Ads API in the Ad Account-Level Rate Limt card. Then, click View Details in the All Remaining Ads API Rate Limit card to view the current usage of your top five ad accounts. Click the chevron of each account to view 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.

Recommendations

  • Switch to other ad accounts and come back to this account later.
  • It is better to create a new ad than to change the existing ones. Updates are 10~100 more resource intensive than creates.

Application-Level Rate Limiting

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

Limits

Rate limting is in real time at the app level over a given time range. The total number of calls your app can make per hour is 200 times the number of Users. This is not 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. However, your top ten most engaged Users could make 19,000 of those calls.

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.

All API calls from an app made after a rate limit is exceeded are throttled and fail with error code = 4, CodedException. Calls 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 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:

  • If a business use case rate limit is applied, the application level rate limiting does not occur.
  • 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.

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'     : 28,  //Percentage of calls made 
  'total_time'     : 15,  //Percentage of total time
  'total_cputime'  : 24   //Percentage of total CPU time
}

The values of call_count, total_time, and total_cputime are whole numbers representing the percentage used of each metric. When any of these metrics exceed 100 the app will be rate limited.

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.

Recommendations

  • 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.

Instagram Rate Limiting

Instagram level rate limiting is part of the Business Use Case rate limiting logic which is separate from the Graph API rate limitations. If you make an Instagram Graph API call, it is not calculated into the Graph API throttling. This rate limit is determined by analyzing the number of impressions.

For Graph API v3.2 and older, apps follow the Application level rate limiting logic until July 30, 2019 when all apps will be automatically migrated to the new logic described in this document. Upgrade to v3.3 now to apply this new logic.

Limits

Rate limiting is in real time at the Instagram account level over a given time range. Each Instagram Graph API call is assigned a score. Your score is the sum of your API calls, the CPU time used, and the total time. The number of calls is 4800 multiplied by the number of impression per 24 hours.

Apps rarely hit CPU time and total time limits, except for specialized endpoints. However, endpoints that require a lot of processing may cause your app to hit these limits, despite being below the call volume limit.

Calls fail with error code 80002, if the call counts, total CPU time, or total time reach 100% usage. Calls succeed again when the usage rate falls back below the limit.

Rate Limiting Header

All responses to calls made to the Instagram Graph API include an x-business-use-case-usage HTTP header. This JSON-formatted string contains your business ID, the current percentage of calls made for that particular Instagram account, the total CPU time, the total time, the type of rate limiting being reported, and the estimated time before you can start making calls again if the account has been throttled.

The following example shows an Instagram account that was throttled due to the call count reaching 100%.

x-business-use-case-usage: {
  '{business-id}':  [{
     'call_count':100,        //Percentage of calls made for this business ad account.
     'total_cputime':56,      //Percentage of the total CPU time that has been used.
     'total_time'45,          //Percentage of the total time that has been used.
     'type':'instagram',                      //Type of rate limit logic being applied.
     'estimated_time_to_regain_access'10      //Time in minutes to resume calls.
  }]
}    

The values for call_count, total_time, and total_cputime are whole numbers representing the percentage used for each of the metrics. When any of the call_count, total_cputime, or total_time reach 100 calls are throttled.

Rate Limit Dashboard

In the app dashboard, click **View Details** in the **Instagram Level Rate Limit card** to view the current percentage of the limit used and time to reset usage for your top five Instagram accounts. Click the chevron of each account to view 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.

You can also search for an account not listed using the search box in the upper right corner using the account ID.

Recommendations

  • When the limit has been reached stop making API calls. Continuing to make calls will continue to increase your call count which will increase the time before calls will be successful again.
  • Check the x-business-use-case-usage HTTP header to see how close your Instagram account is to its limit and when you can resume making calls.
  • Verify the error code and API endpoint to confirm the throttling type.

Page Level Rate Limiting

The Page Level Rate Limiting is part of the Business Use Case rate limiting logic which is separate from the Graph API rate limitations. If your make a Pages API call, it is not calculated into the Graph API throttling. These Pages API calls are made using a page or system user access token. Any Pages API calls not made with a page or system user access token default to the application-level or user-level rate limits.

For Graph API v3.2 and older, apps follow the Application level rate limiting logic and User level rate limiting until July 30, 2019 when all apps will be automatically migrated to the new Business Use Case rate limiting logic described in this document. Upgrade to v3.3 now to apply this new logic.

Limits

Rate limiting is in real time at the Page level over a given time rage. Each Pages API call is assigned a score. Your score is the sum of your API calls, the CPU time used, and the total time. The number of calls is 4800 multiplied by the number of engaged Users per 24 hours.

Apps rarely hit CPU time and total time limits, except for specialized endpoints. However, endpoints that require a lot of processing may cause your app to hit these limits, despite being below the call volume limit. Information about endpoints that are using a lot of CPU time or total time can be seen in the app dashboard.

Calls fail with error code 80001 if the call counts, total CPU time, or total time reach 100%. Calls start to succeed again when the usage rate falls back below the limit.

For v3.2 and Older Apps

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 throttled and fail with error code 32. 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.

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-business-use-case-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:

x-business-use-case-usage: {
  '{business-id}':
    [{'call_count':100,           //Percentage of calls made for this business Page. 
      'total_cputime':34,         //Percentage of the total CPU time that has been used.
      'total_time':16,            //Percentage of the total time that has been used.
      'type':'pages',                             //Type of rate limit logic being applied.
      'estimated_time_to_regain_access':19}]      //Time in minutes to regain access.
}`

The values for call_count, total_time, and total_cputime are whole numbers representing the percentage used for each of the metrics. When any of the call_count, total_cputime, or total_time reach 100 calls are throttled.

For v3.2 and Older

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

{
  'call_count'    : 28,  //Percentage of calls made.
  'total_time'    : 15,  //Percentage of total time that has been used.
  'total_cputime' : 24   //Percentage of total CPI time that has been used.
}

The values for call_count, total_time, and total_cputime are whole numbers representing the percentage used for each of the metrics. When any of the call_count, total_cputime, or total_time reach 100 calls are throttled.

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.

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.

  • When the limit has been reached stop making API calls. Continuing to make calls will continue to increase your call count which will increase the time before calls will be successful again.

  • Check the x-business-use-case-usage HTTP header to see how close your Instagram account is to its limit and when you can resume making calls.
  • Verify the error code and API endpoint to confirm the throttling type.

User Level Rate Limiting

These limits apply to calls made using User access tokens.

Limits

Rate limiting is in real time at the User level over a given time range, a rolling one hour window. The total number of calls by a User is limited and when a User makes too many calls to the API (possibly through other apps), they are rate limited.

All API calls from an app made after a rate limit is exceeded are throttled and will fail with error code 17. Calls will start to succeed again when the usage over the past hour falls back below the limit.

When a User is rate limited, API calls from that User are throttled.

Rate Limit Dashboard

For each User whose access token is used by your app to make calls, the User Level Rate Limit card on your app's dashboard landing page shows the current percentage of the limit used.

Recommendations

  • 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.

The following table illustrates this concept.

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 that 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 your 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 Limit Error Code

Ads Insights level

Not applicable

80000 with sub-code 2446079

Application level

200 calls/person/hour

4

Ad Account level

Not applicable

17 with subcode 2446079

Custom level

Not applicable

613

Instagram level

4800 x the number of impression per 24 hours

80002

Page level v3.3

4800 x the number of engaged Users per 24 hours

80001

Page level v3.2

4800 calls/person/24-hours

32

User level

Not applicable

17

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

If your error response contains error_subcode 1996, we have 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 file a bug for help resolving this issue.

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

If you are building a service that scrapes data, please read our scraping terms.