Rate Limiting

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 should be encountered only in rare circumstances. This document describes what those limits are and how to handle them.

Starting with the Graph API v4.0 release on July 29, 2019, we made changes to our rate limiting system for businesses integrating with Facebook Business APIs for Ads Management, Custom Audiences, Lead Generation, and Messenger including new headers for the new rate limiting logic.

This is a 90-day breaking change. All apps will be automatically migrated to this new logic on October 29, 2019. Upgrade to v4.0 to apply this new logic.

For the Insights API, you can retrieve for each ad account in a one-hour time period: 190000 items if your app is in the Standard tier or 60 if your app in in the Dev tier + 400 * Number of Active ads - 0.001 * User Errors.

Platform Rate Limiting

Business Use Case Rate Limiting

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

Platform Rate Limiting

The Platform Rate Limiting is our rate limiting system for Application-Level and User-Level rate limits.

Application-Level Rate Limiting

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

Limits

Rate limiting 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 More 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.

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

In the app dashboard, click Rate Limit Monitoring and scroll to the User-Level Rate Limit card. 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.

Business Use Case Rate Limiting

The Business Use Case Rate Limiting is our rate limiting system for businesses integrating with Facebook Business APIs for Ads Insights, Ads Management, Custom Audience, Instagram, Lead Generation, Messenger, and Pages.

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.

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.

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

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

Ads Management Level Rate Limiting

Ads Management 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 Management call, it won't be calculated into the Graph API throttling. Ads Management rate limiting is determined by analyzing your app access tier and the number of ads in your ad account.

Limits

Rate limiting is in real time at the ad account level over a given time range. Each Ads Management API call is assigned a score. Your score is the sum of your API calls. Calls fail if the call counts, total cup time, or total time reach 100% usage. All API calls from an app made after a rate limit is exceeded are throttled and will fail with error code 80004, 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 Ads Management API include an x-business-use-case-usage HTTP header. This header 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 rate limiting header is a JSON-formatted string. The following example shows a business account that has been throttled.

x-business-use-case-usage: {
  '{business-asset-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_management',            //Type of rate limit logic being applied.
    'estimated_time_to_regain_access': 10         //Time in minutes to resume calls.
  }]
}   

When any of the call_count, total_cputime, or total_time reach 100% the ad account will be rate limited.

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 account is to its limit and when you can resume making calls.
  • Verify the error code and API endpoint to confirm the throttling type.

Custom Audience Level Rate Limiting

Custom Audience rate limiting is part of the Business Use Case rate limiting logic which is separate from the Graph API rate limitations. If you make a Custom Audience call, it won't be calculated into the Graph API throttling. Custom Audience rate limiting is determined by analyzing your app access tier and the number of custom audiences in your ad account.

Limits

Rate limiting is in real time at the ad account level over a given time range. Each Custom Audience API call is assigned a score. Your score is the sum of your API calls. Calls fail if the call counts, total cup time, or total time reach 100% usage. All API calls from an app made after a rate limit is exceeded are throttled and will fail with error code 80003, 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 Custom Audience API include an x-business-use-case-usage HTTP header. This header contains your business asset 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 rate limiting header is a JSON-formatted string. The following example shows a business account that has been throttled.

x-business-use-case-usage: {
  '{business-asset-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': 'custom_audience',                     //Type of rate limit logic being applied.
    'estimated_time_to_regain_access': 10         //Time in minutes to resume calls.
  }]
}    

When any of the call_count, total_cputime, or total_time reach 100% the ad account will be rate limited.

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 account is to its limit and when you can resume making calls.
  • Verify the error code and API endpoint to confirm the throttling type.

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 to the instagram_basic, instagram_comments_moderation, or instagram_manage_insights endpoint, it is not calculated into the Graph API throttling. This rate limit is determined by analyzing the number of impressions.

Note: Not all Instagram endpoints are calculated using the Business Use Case Rate Limiting logic. Only queries of your Instagram Account data are subject to this rate limiting logic. For all other Instagram endpoints, including queries of public data, please see the Application Level rate limiting section.

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.

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.

LeadGen Level Rate Limiting

LeadGen 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 a Lead Generation API call, it won't be calculated into the Graph API throttling. Lead Generation rate limiting is determined by the number of leads created in the past 30 days.

Limits

Rate limiting is in real time at the ad account level over a given time range. Each API call is assigned a score. Your score is the sum of your API calls. Calls fail if the call counts, total cup time, or total time reach 100% usage. All API calls from an app made after a rate limit is exceeded are throttled and will fail with error code 80005, Calls succeed again when the usage rate falls back below the limit.

Rate Limiting Header

All responses to calls made to the Lead Generation API include an x-business-use-case-usage HTTP header. This header contains your business ID, the percentage of calls made for that particular page, 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 rate limiting header is a JSON-formatted string. 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': 'leadgen',            //Type of rate limit logic being applied.
    'estimated_time_to_regain_access': 10         //Time in minutes to resume calls.
  }
]}    

When any of the call_count, total_cputime, or total_time reach 100% the ad account will be rate limited.

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 account is to its limit and when you can resume making calls.
  • Verify the error code and API endpoint to confirm the throttling type.

Messenger Level Rate Limiting

Messenger 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 a Messenger call, it won't be calculated into the Graph API throttling. Messenger level rate limiting is determined by the number of people your business can send messages to.

Limits

Rate limiting is in real time at the Messenger account level over a given time range. Each API call is assigned a score. Your score is the sum of your API calls. Calls fail if the call counts, total cup time, or total time reach 100% usage. All API calls from an app made after a rate limit is exceeded are throttled and will fail with error code 80006. Calls succeed again when the usage rate falls back below the limit.

Rate Limiting Header

All responses to calls made to the Messenger API include an x-business-use-case-usage HTTP header. This header contains your business ID, the percentage of calls made for that particular page, 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 rate limiting header is a JSON-formatted string. 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': 'messenger',            //Type of rate limit logic being applied.
    'estimated_time_to_regain_access': 10         //Time in minutes to resume calls.
  }]
}    

When any of the call_count, total_cputime, or total_time reach 100% the ad account will be rate limited.

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

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.

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.

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.

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. Visit specific API docs for custom rate limits that may be applied 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.