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 may be throttled. API requests made by a throttled user or app will fail.

All API requests are subject to rate limits. Graph API and Instagram Basic Display API requests are subject to Platform Rate Limits, while Marketing API and Instagram Platform 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.

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:

The Number of Users is based on the number of unique daily active users an app has. 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 20,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

X-Ad-Account-Usage Header Contents

Total CPU Time

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

Total Time

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

Sample X-App-Usage Header Value

x-app-usage: {
    "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.
    "reset_time_duration": 100,   //Time duration (in seconds) it takes to reset the current rate limit score.
    "ads_api_access_tier": 'standard_access'   //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
}

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

Sample Response

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

Facebook Stability Throttle Codes

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 Case (BUC) Rate Limits, and depend on the endpoints you are querying.

For Marketing API, the rate limit is applied to the ad account across the same Business Use Case. For example, all endpoints with the Ads Management business use case will share the total quota within the same ad account. If a certain endpoint makes a lot of API requests and causes throttling, other endpoints configured with the same business use case will also receive rate limiting errors. The quota depends on the app's Marketing API Access Tier. The standard access Marketing API tier will have more quotas than the development access Marketing API tier. By default, an new app should be on the development tier. If you need to upgrade to get more rate limiting quota, upgrade to Advanced Access of Ads Management Standard Access in App Review.

Ads Insights

Requests made by your app to the Ads Insights API are counted against the app's rate limit metrics such as call count, total CPU time and total time. 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 apps with Standard Access to the Ads Management Standard Access feature:

For apps with Advanced Access to the Ads Management Standard Access feature:

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. To get a higher rate limit, you can apply for the Ads Management Standard Access feature.

Rate limiting may also be subject to the total CPU time and total wall time during a rolling one hour window. For more details, check the HTTP X-Business-Use-Case header total_cputime and total_time.

If you are receiving rate limiting errors, you can also refer to estimated_time_to_regain_access in the X-Business-Use-Case header for the estimated blocking time.

Ads Management

Requests made by your app to the Ads Management API are counted against the app's rate limit metrics such as call count, total CPU time and total time. 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 apps with Standard Accessto the Ads Management Standard Access feature:

For apps with Advanced Access to the Ads Management Standard Access feature:

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

Rate limiting may also be subject to the total CPU time and total wall time during a rolling one hour window. For more details, check the HTTP X-Business-Use-Case header total_cputime and total_time.

If you are receiving rate limiting errors, you can also refer to estimated_time_to_regain_access in the X-Business-Use-Case header for the estimated blocking time.

Catalog

Catalog Batch

Requests made by your app are counted against the rate limit metrics such as call count, total CPU time and total time your app can make in a rolling one hour period per each catalog ID and is calculated as follows:

The unique users is a number of unique users of the business (on all catalogs) with intent in the last 28 days. The more users see products from your catalogs, the more call quota is allocated.

Catalog Management

Requests made by your app are counted against the number of calls your app can make in a rolling one hour period per each catalog ID and is calculated as follows:

The unique users is a number of unique users of the business (on all catalogs) with intent in the last 28d. The more users see products from your catalogs, the more call quota is allocated.

This formula is applied on various catalog endpoints.

For more information on how to get your current rate usage, see Headers.

Rate limiting may also be subject to the total CPU time and total wall time during a rolling one hour window. For more details, check the HTTP X-Business-Use-Case header total_cputime and total_time.

If you are receiving rate limiting errors, you can also refer to estimated_time_to_regain_access in the X-Business-Use-Case header for the estimated blocking time.

Custom Audience

Requests made by your app to the Custom Audience API are counted against the app's rate limit metrics such as call count, total CPU time and total time. 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 apps with Standard Access to the Ads Management Standard Access feature:

For apps with Advanced Access to the Ads Management Standard Access feature:

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

Rate limiting may also be subject to the total CPU time and total wall time during a rolling one hour window. For more details, check the HTTP X-Business-Use-Case header total_cputime and total_time.

If you are receiving rate limiting errors, you can also refer to estimated_time_to_regain_access in the X-Business-Use-Case header for the estimated blocking time.

Instagram Platform

LeadGen

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:

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

Messenger Platform

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 24 hour window and is calculated as follows:

The Number of Engaged Users is the number of Users who engaged with the 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.

To avoid rate limiting issues when using the Page Public Access Content feature, using a system user access token is recommended.

Spark AR Commerce Effect Management

Requests made by your app to any Commerce endpoints 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:

The Number of Catalogs is the total number of catalogs across all commerce accounts managed by your app.

Threads

WhatsApp Business Management API

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

Total CPU Time

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

Total Time

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

Ads API Access Tier

For ads_insights and ads_management types only. Tiers allows your app to access the Marketing API. By default, apps are in the development_access tier. Standard_access enables lower rate limiting. To get a higher rate limit and get to the standard tier, you can apply for the "Advanced Access" to the Ads Management Standard Access feature.

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.
            "ads_api_access_tier": "standard_access"  //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
        }
    ],      
    "66782684": [
        {
            "type": "ads_management",
            "call_count": 95,
            "total_cputime": 20,
            "total_time": 20,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access" 
        }
    ],
    "10153848260347724": [
        {
            "type": "ads_insights",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access"
        }
    ],
    "10153848260347724": [
        {
            "type": "pages",
            "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.

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.

We strongly recommend specifying 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.