Meta's x-app-usage header Is Three Percentages and No Clock

What is the x-app-usage header?

Meta returns the x-app-usage header on Graph API responses to tell an app how much of its own rate limit it has already spent. The rate limiting reference introduces it in one sentence: "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."

Two conditions hide in that sentence. The header belongs to the app, not to the account or the user whose token made the call. And it arrives only on endpoints that have seen enough traffic, which Meta restates elsewhere as headers "included with most API responses once enough calls have been made to an endpoint." A response with no x-app-usage means Meta declined to report, not that usage is zero.

The value is a JSON object with three keys and nothing else. Meta's own sample:

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
}

Which requests get this header rather than another one comes down to the API and the token. Meta splits it cleanly: "Graph 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 calls land on either side depending on the credential, with application and user access tokens on the Platform side and system user or Page access tokens on the business use case side.

What do the three fields in x-app-usage mean?

All three are percentages of an allowance, not counts of anything.

The word "whole" is doing real work. Every value in x-app-usage is an integer, so the finest reading you get is one percent of the budget. Meta's other app-level header is more precise about the same idea: the acc_id_util_pct field in X-Ad-Account-Usage shows up in the sample as 9.67, with decimals. x-app-usage rounds.

The three fields also throttle independently. Meta attaches the same two lines to both time fields: "When total_cputime reaches 100, calls may be throttled" and "When total_time reaches 100, calls may be throttled." A handful of expensive queries can drive total_cputime toward the ceiling while call_count is still in single digits, so an app that only watches call volume misses two of the three ways it gets blocked.

Notice what Meta does not publish there. The reference states a threshold for total_cputime and a threshold for total_time and never writes the matching sentence for call_count in the Platform headers section. What it says instead is general: "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." Read 100 on call_count as the limit anyway, because nothing in the document suggests a different number.

What allowance are the percentages measured against?

An app-level formula that Meta publishes in full: Calls within one hour = 200 * Number of Users.

The multiplier is fixed and the multiplicand is engagement. Meta defines it as "the number of unique daily active users an app has", with a fallback for uneven traffic: "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." Installs do not enter into it. Meta says so directly: apps with high daily engagement get higher limits "regardless of the actual number of app installs."

The pool is shared rather than divided. Meta works the arithmetic itself: "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." One noisy account can starve the rest of an app's users inside the same hour, and nothing in the Platform limit prevents it.

User tokens carry a second, separate count that no header reports. A user's own call count runs on its own rolling hour and spans every app they use, so Meta warns that a user "could make X calls through App1 and Y calls through App2" and get limited on the total. Then it closes the door on measuring it: "Due to privacy concerns, we do not reveal actual call count values for users." There is no x-user-usage header. The user side of Platform Rate Limits is unobservable by design.

One counting rule catches people who batch. Meta's FAQ states that "each ID counts as one API call" and demonstrates it: three separate single-ID requests count as three calls, and one request with ids=4,5,6 also counts as three. Batching improves response performance and buys no quota. That is a different accounting model from the per-endpoint request ceilings Bluesky publishes and from Pinterest's split between app-level and user-level ceilings.

How is x-app-usage different from the business use case header?

Different scope, different shape, and one of them tells you when you get back in.

The business use case header is the richer of the two, and it is the one that matters for Instagram publishing work. Meta's 4800 times impressions formula and the fields in X-Business-Use-Case-Usage are covered in depth separately, including the type values and the error codes attached to each.

Where the two headers touch, Meta's own document contradicts itself. The Platform section attaches the parenthetical "(for v3.3 and older Ads API calls)" to X-Ad-Account-Usage, which is what it describes. The business use case section then repeats the same parenthetical on a different header: "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." The business use case header is not restricted to v3.3 and older calls, and the rest of that same section documents it as the current mechanism for Instagram and Marketing API traffic. Treat the qualifier as a copy and paste artefact.

The precedence rule between the two is the one line worth memorising: "If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied."

What happens when x-app-usage reads 100?

Calls start failing with a numbered error, and which number depends on whose limit broke.

Meta's guidance on all of them is the same and it is not a backoff policy: "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."

That is the sentence most retry loops get wrong. Exponential backoff still sends requests, and by Meta's account each one pushes the unblock time further out. The correct response to error code 4 is to park the queue, not to slow it down.

Then comes the gap. Meta's own best practice for recovering says: "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." The header has three fields, all of them percentages, and not one of them is a time. estimated_time_to_regain_access exists on the business use case header. reset_time_duration exists on X-Ad-Account-Usage. Neither exists on x-app-usage. Meta tells you to read a resume time out of a header that does not carry one.

What you get instead is the App Dashboard, where Meta displays "the app's current Application Rate Limits usage percentage" and average activity for the past seven days. That is a chart for humans, not a field your retry logic can read. The practical approach is to watch call_count climb, stop well short of 100, and spread traffic evenly, which is also Meta's stated advice: "Spread out queries evenly to avoid traffic spikes." Publishing schedules run into the separate, unnumbered ceilings too, and Facebook's daily posting limits are their own system with their own behaviour.

Frequently asked questions

What are the three fields in the x-app-usage header?

call_count, total_cputime and total_time. Meta defines each as a whole number expressing a percentage, of calls made over a rolling hour and of the CPU time and total time allotted for query processing.

What is the app-level Graph API rate limit behind call_count?

Calls within one hour = 200 * Number of Users, where the number of users is Meta's count of unique daily active users for the app, falling back to weekly and monthly actives when daily traffic is uneven.

Which error code means the x-app-usage limit was hit?

Error code 4, which Meta names "API Too Many Calls". Code 17 covers the user's own limit, and code 32 covers Pages API calls made with a user or app access token.

Does x-app-usage say when the block ends?

No. It carries three percentages and no time field, even though Meta's best practices tell you to check it for when you can resume. estimated_time_to_regain_access belongs to the business use case header, not this one.

Does the x-app-usage header appear on every response?

No. Meta returns it on endpoints "that receive enough requests from your app", so a missing header carries no information at all and should never be read as zero usage.

Which requests get x-app-usage instead of X-Business-Use-Case-Usage?

Graph API requests under Platform Rate Limits. Marketing API and Instagram Platform requests get the business use case header, and where both could apply, Meta states that the business use case limits win.

What counts as a user in the 200 times users rate limit formula?

Meta defines it as the number of unique daily active users an app has. When daily traffic swings between weekdays and weekends, weekly and monthly active users are used instead. Installs do not factor in at all, since apps with high engagement get higher limits regardless of the actual number of app installs.

Can one user burn through an app's entire rate limit?

One heavy user can. Meta's own arithmetic shows an app with 100 users gets a 20,000-call hourly pool, and the ten most engaged users could account for 19,000 of those calls. The pool is shared rather than divided, so nothing in the Platform limit stops one account from starving the rest of the app's users within the same hour.

Does bundling multiple IDs into one request save on the rate limit?

Bundling does not reduce what counts against the quota. Meta's FAQ states each ID counts as one API call, so three separate single-ID requests and one request with ids=4,5,6 both count as three calls. Batching improves response performance, not the budget.

How does x-app-usage differ from X-Ad-Account-Usage?

X-Ad-Account-Usage reports its acc_id_util_pct field with decimals, shown in Meta's sample as 9.67, while every field in x-app-usage rounds to a whole percentage. X-Ad-Account-Usage also carries reset_time_duration, a field x-app-usage lacks, and the header is tied to v3.3 and older Ads API calls.