Rate Limits

A rate limit is the number of API calls an app or user can make within a given time period. If this limit is exceeded or if CPU or total time limits are exceeded the app or user will be throttled and API requests will fail.

All API requests are subject to rate limits. Graph API requests are subject to Platform Rate Limits and Marketing API requests are subject to Business Use Case (BUC) Rate Limits.

Pages API requests are subject to either Platform or BUC Rate Limits, depending on the token used in the request; requests made with application or user access tokens are subject to Platform Rate Limits, while requests made with system user or page access tokens are subject to Business Use Case Rate Limits.

Real time rate limit usage statistics are described in headers that are included with most API responses once enough calls have been made to an endpoint. Platform Rate Limit usage statistics are also displayed in the App Dashboard. Once a rate limit is reached, any subsequent requests made by your app will fail and the API will return an error code until enough time has passed for the call count to drop below the limit.

If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied.

Starting with the Graph API v4.0 release on July 29, 2019, we made changes to our rate limit system for businesses integrating with with the following APIs:

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

Platform Rate Limits

Platform Rate Limits are tracked on an individual application or user level, depending on the type of token used in the request.

Applications

Graph API requests made with an application access token are counted against that app’s rate limit. An app’s call count is the number of calls it can make during a rolling one hour window and is calculated as follows:

Calls within one hour = 200 * Number of Users

Number of Users is the sum of the average number of unique daily active over the last 28 days and the current day’s new logins. In cases where there are slow periods of daily usage, such as if your app has high activity on weekends but low activity over weekdays, the weekly and 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.

Note that this is not a per User limit but a limit on calls made by your app. Any individual User can make more than 200 calls per hour using your app, as long as the total calls from your app does not exceed the app maximum. For example, if your app has 100 Users, your app can make 24,000 calls per hour. However, your top ten most engaged Users could make 19,000 of those calls.

Users

Graph API requests made with a user access token are counted against that user’s call count. A user’s call count is the number of calls a user can make during a rolling one hour window. Due to privacy concerns, we do not reveal actual call count values for users.

Note that a user’s call count can be spread over multiple apps. For example, a user could make X calls through App1 and Y calls through App2. If X+Y exceeds the user’s call count that user will be rate limited. This does not necessarily mean that any app is doing something wrong; it could be that the user is using multiple apps or is misusing the API.

Headers

Endpoints that receive enough requests from your app will include a X-App-Usage or X-Ad-Account-Usage (for v3.3 and older Ads API calls) HTTP header in their responses. The header will contain a JSON-formatted string that describes current application rate limit usage.

Header Contents

KeyValue Description

call_count

A whole number expressing the percentage of calls made by your app over a rolling one hour period.

total_cputime

A whole number expressing the percentage of CPU time allotted for query processing.

total_time

A whole number expressing the percentage of total time allotted for query processing.

Total CPU Time

The amount of CPU time the request takes to process. When total_cputime reaches 100, calls will be throttled.

Total Time

The length of time the request takes to process. When total_time reaches 100, calls will be throttled.

Sample X-App-Usage Header Value

{
  'call_count'     : 28,  //Percentage of calls made 
  'total_time'     : 25,  //Percentage of total time
  'total_cputime'  : 25   //Percentage of total CPU time
}

Sample X-Ad-Account-Usage Header Value

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

Dashboard

The app dashboard displays the number of rate limited app users, the app’s current Application Rate Limits usage percentage, and displays average activity for the past 7 days. In the Application Rate Limit card, click View Details and 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.

Error Codes

When an app or user has reached their rate limit, requests made by that app or user will fill and the API will respond with an error code.

Throttle Error Codes

Error CodeDescription

4

Indicates that the app whose token is being used in the request has reached its rate limit.

17

Indicates that the User whose token is being used in the request has reached their rate limit.

17 with subcode 2446079

Indicates that the token being used in the Ads API v3.3 or older request has reached its rate limit.

32

Indicates that the User or app whose token is being used in the Pages API request has reached its rate limit.

613

Indicates that a custom rate limit has been reached. To help resolving this issue, visit the supporting docs for the specific API you are calling for custom rate limits that may be applied.

613 with subcode 1996

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

Sample Response

{
  "error": {
    "message": "(#32) Page request limit reached",
    "type": "OAuthException",
    "code": 32,
    "fbtrace_id": "Fz54k3GZrio"
  }
}

Best Practices

  • 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.
  • Spread out queries evenly to avoid traffic spikes.
  • Use filters to limit the data response size and avoid calls that request overlapping data.
  • Check the `X-App-Usage` HTTP header to see how close your app is to its limit and when you can resume making calls when the limit has been reached.
  • If Users are being throttled, be sure your app is not the cause. Reduce the user’s calls or spread the user’s calls more evenly over time.

Business Use Case Rate Limits

All Marketing API requests, and Pages API requests made with a system or page access token, are subject to Business Use Care (BUC) Rate Limits, and depend on the endpoints you are querying.

Ads Insights

Requests made by your app to the Ads Insights API are counted against the app’s call count. An app’s call count is the number of calls it can make during a rolling one hour window and is calculated as follows:

For public apps:

Calls within one hour = 190000 + 400 * Number of Active ads - 0.001 * User Errors

For dev apps:

Calls within one hour = 60 + 400 * Number of Active ads - 0.001 * User Errors

The Number of Active ads is the number of ads currently running per ad account. User Errors is the number of errors received when calling the API.

Ads Management

For v4.0+, apps follow the BUC rate limits.

Requests made by your app to the Ads Management API are counted against the app’s call count. An app’s call count is the number of calls it can make during a rolling one hour window and is calculated as follows:

For public apps:

Calls within one hour = 100000 + 40 * Number of Active Ads

For dev apps:

Calls within one hour = 300 + 40 * Number of Active Ads

The Number of Active Ads is the number of ads for each ad account.

For Graph API v3.3 and older, apps follow the Marketing API rate limit logic until October 29, 2019 when all apps will be automatically migrated to the BUC logic.

Custom Audience

For v4.0+, apps follow the BUC rate limits.

Requests made by your app to the Custom Audience API are counted against the app’s call count. An app’s call count is the number of calls it can make during a rolling one hour window and is calculated as follows but will never exceed 700000:

For public apps:

Calls within one hour = 190000 + 40 * Number of Active Custom Audiences

For dev apps:

Calls within one hour = 5000 + 40 * Number of Active Custom Audiences

The Number of Active Custom Audiences is the number of active custom audiences for each ad account.

For Graph API v3.3 and older, apps follow the Marketing API rate limit logic until October 29, 2019 when all apps will be automatically migrated to the BUC logic.

Instagram

Requests made by your app to the Instagram Graph API are counted against the app’s call count. An app’s call count is the number of calls during a rolling 24 hour window and is calculated as follows:

Calls within 24 hours = 4800 * Number of Impressions

The Number of Impressions is the number of times any content from your Instagram account entered a person's screen.

Note: Requests made by your app to the Business Discover and Hashtag APIs follow the Platform Rate limit logic.

LeadGen

For v4.0+, apps follow the BUC rate limits

Requests made by your app to the LeadGen API are counted against the app’s call count. An app’s call count is the number of calls it can make during a rolling 24 hour window and is calculated as follows:

Calls within 24 hours = 4800 * Leads Generated

The Number of Leads Generated is the number of leads generated per Page for this Ad Account over the past 30 days.

For Graph API v3.3 and older, apps follow the Marketing API rate limit logic until October 29, 2019 when all apps will be automatically migrated to the BUC logic.

Messenger

For v4.0+, apps follow the BUC rate limits

Requests made by your app to the Messenger API are counted against the app’s call count. An app’s call count is the number of calls per page it can make during a rolling 24 hour window and is calculated as follows:

Calls within 24 hours = 4800 * Number of Engaged Users

The Number of Engaged Users is the number of Users your app can send messages to.

For Graph API v3.3 and older, apps follow the Marketing API rate limit logic until October 29, 2019 when all apps will be automatically migrated to the BUC logic.

Pages

The Page Rate Limits may use either the Platform or BUC rate limit logic depending on the type of token used. Any Pages API calls that are made using a Page or system user access token use the rate limit calculation below. Any calls made with application or user access tokens are subject to application or User rate limits.

Requests made by your app to the Pages API using a Page access token or system User access token are counted against the app’s call count. An app’s call count is the number of calls it can make during a rolling one hour window and is calculated as follows:

Calls within one hour = 4800 * Number of Engaged Users

The Number of Engaged Users is the number of Users who engaged with your Page per 24 hours.

Requests made by your app to the Pages API using a User access token or App access token follow the Platform Rate Limit logic.

Headers

All API responses made by your app that are rate limited using the BUC logic include an X-Business-Use-Case-Usage (for v3.3 and older Ads API calls) HTTP header with a JSON-formatted string that describes current application rate limit usage. This header can return up to 32 objects in one call.

X-Business-Use-Case Usage Header Contents

Error CodeValue Description

business-id

The ID of the business associated with the token making the API calls.

call_count

A whole number expressing the percentage of allowed calls made by your app over a rolling one hour period.

estimated_time_to_regain_access

Time, in minutes, until calls will not longer be throttled.

total_cputime

A whole number expressing the percentage of CPU time allotted for query processing.

total_time

A whole number expressing the percentage of total time allotted for query processing.

type

Type of rate limit applied. Value can be one of the following: ads_insights, ads_management, custom_audience, instagram, leadgen, messenger, or pages.

Total CPU Time

The amount of CPU time the request takes to process. When total_cputime reaches 100, calls will be throttled.

Total Time

The length of time the request takes to process. When total_time reaches 100, calls will be throttled.

Sample X-Business-Use-Case-Usage Header Value

x-business-use-case-usage: {
    "{business-object-id}": [
        {
            "type": "{rate-limit-type}",           //Type of BUC rate limit logic being applied.
            "call_count": 100,                     //Percentage of calls made. 
            "total_cputime": 25,                   //Percentage of the total CPU time that has been used.
            "total_time": 25,                      //Percentage of the total time that has been used.   
            "estimated_time_to_regain_access": 19  //Time in minutes to regain access.
        }
    ],      
    "66782684": [
        {
            "type": "ads_management",
            "call_count": 95,
            "total_cputime": 20,
            "total_time": 20,
            "estimated_time_to_regain_access": 0
        }
    ],
    "10153848260347724": [
        {
            "type": "ads_management",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0
        }
    ],
...
}

Error Codes

When your app reaches its Business Use Case rate limit, subsequent requests made by your app will fail and the API will respond with an error code.

Error CodeBUC Rate Limit Type

error code 80000, error subcode 2446079

Ads Insights

error code 80004, error subcode 2446079

Ads Management

error code 80003, error subcode 2446079

Custom Audience

error code 80002

Instagram

error code 80005

LeadGen

error code 80006

Messenger

error code 32

Page calls made with a User access token

error code 80001

Page calls made with a Page or System User access token

error code 17, error subcode 2446079

V3.3 and Older Ads API excluding Ads Insights

SampleError Code Message

{   
"error": {      
    "message": "(#80001) There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.",      
    "type": "OAuthException",      
    "code": 80001,      
    "fbtrace_id": "AmFGcW_3hwDB7qFbl_QdebZ"   
    }
}

Best Practices

  • 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.
  • Spread out queries evenly between two time intervals to avoid sending traffic in spikes.
  • Use filters to limit the data response size and avoid calls that request overlapping data.

FAQ

What do we consider an API call?

All calls count towards the rate limits, not just individual API requests. For example, you can make a single API request specifying multiple IDs, but each ID counts as one API call.

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

We strongly recommend specify multiple IDs in one API request when possible as this improves performance of your API responses.

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.