X API usage: the dollar figure the API withholds

#Quick answer

X ships two usage endpoints and neither one answers "what did I spend." GET /2/usage/tweets counts Posts consumed. GET /2/usage/credits counts dollars remaining. There is no endpoint that reports dollars spent, and none that breaks spend down by route, so per-endpoint cost attribution is a Developer Console screen and nothing else. The credits endpoint is also effectively hidden: it has no entry in X's documentation index and the string credits appears zero times in the official Python SDK.

Last updated: November 2026

Every number below is checked against the live API description at api.x.com/2/openapi.json, version 2.174, X's usage, billing, pricing and rate-limit pages, and the published Python SDK wheel. All read on 9 November 2026.

#Two endpoints, two units

That is the whole surface. Put them side by side and the gap is obvious: one meter counts things, the other counts money, and nothing converts between them. You can learn that your project consumed 41,000 Posts last week and that you have $12.60 left. You cannot learn, from the API, that the user-lookup job cost $9 of it.

Auth splits here too, and it matters. /2/usage/tweets accepts only an app-only Bearer token, which makes sense for a project-scoped meter. /2/usage/credits accepts an OAuth 2.0 user token or a Bearer token, and notably not the OAuth 1.0a user token that most other routes still allow. If you are deciding which credential to mint, how to get an X API key covers the three flows.

#The credits endpoint is real, and nearly unfindable

GET /2/usage/credits is in the live spec with a written description, and its reference page renders at docs.x.com/x-api/usage/get-usage-credits. Three things make it hard to reach:

• docs.x.com/llms.txt, the index X publishes for machine readers, contains no x-api/usage entries at all.
• The x-api section index lists exactly two usage pages, "Get Usage" and the "Usage" overview. The credits reference is not one of them.
• X's pricing page, the canonical billing document, says your credit balance "is displayed in the Developer Console" and never names the endpoint.

Its only published link is one row in a two-row table on the Usage overview page. And the official SDK has not caught up: in xdk 0.10.6 the usage client exposes a single method, get, bound to /2/usage/tweets, and the string credits appears zero times in the entire package. That dates the endpoint to after 25 July 2026, which is the same pattern described in X API Python for every field that lands between SDK releases. Call it with plain HTTP.

What comes back is more useful than a single number:

All four are required fields, so you always get the full picture.

#The clamp that hides an overdraft

total_balance bottoms out at zero. prepaid_balance does not. X's pricing page states that a balance can go "slightly negative," that API requests are blocked until you add credits to cover it, and separately that auto-recharge "does not run while your account balance is zero or negative."

Chain those three facts and you get a failure mode worth coding against. A monitor that alerts on total_balance == 0 tells you that you are blocked but not by how much, because the clamp has thrown away the deficit. Auto-recharge will not dig you out, because it is paused in exactly that state. Read prepaid_balance to size the top-up, and treat any negative value there as requiring a manual purchase rather than waiting for the trigger threshold to fire.

That free_grants array is the other reason to call this endpoint rather than read a dashboard. Free credits expire three months after they are granted and are spent before purchased credits, so a balance of $70 can be mostly air if the grants lapse next week. The array gives you each grant's remaining amount and its expires_at, soonest first, with expires_at simply omitted when a grant never expires or the date is unknown. X API pricing covers how those grants are earned and the 13 October 2026 change to the eligibility rule.

#The Posts meter, and the example that does not match it

Two parameters shape the Posts meter. days is an integer between 1 and 90 and defaults to 7. usage.fields is a comma-separated list drawn from six values:

cap_reset_day, daily_client_app_usage, daily_project_usage,
project_cap, project_id, project_usage

Here is where it gets awkward. The response example X publishes on the Usage overview page disagrees with X's own API description in four ways:

X's example also omits cap_reset_day, project_usage and the entire daily_client_app_usage branch, and the field table printed underneath it repeats app_id and tweets_consumed as if they were real.

Once again the SDK settles which one to trust, because it is generated from the same description the docs site renders. In xdk 0.10.6, tweets_consumed appears zero times and client_app_id appears five. Write your parser against the spec, parse the daily counts as strings, and expect nulls.

One more detail on that page: the project_cap in the example reads 10,000,000, while a note at the top of the same page states that pay-per-usage plans are capped at 3 million Post reads a month. Treat the 3 million as the published figure and your own project_cap value as the authority for your project.

Worth checking the search results before you copy anything: the pages ranking for this query reproduce app_id and tweets_consumed verbatim, because they were written from X's example rather than from the description. That is the same reseller-blog pattern that shows up across API topics, and the fix is always to read the spec.

#50 calls per 15 minutes

X's rate-limit page has a section headed "Usage (1 endpoint)" with a single row:

Fifty per fifteen minutes is tight for a monitoring endpoint. It is the same ceiling X puts on opening a filtered stream connection, and one sixth of the 300 per 15 minutes a normal lookup route gets. In practice it means a poll every 20 seconds fits with room to spare and a poll every 15 seconds does not. Pull it on a one-minute timer and cache, especially if more than one process wants the number.

There is no rate-limit row anywhere for GET /2/usage/credits on that page, which is the same gap documented for other recently shipped routes in X API rate limits. Treat it as unpublished rather than unlimited and poll it conservatively.

#What counts toward the cap

Seven categories of endpoint draw down the 3 million, per the billing page:

Post lookup, recent and full-archive search, filtered stream and filtered stream webhooks, user Posts and user mentions timelines, liked Posts and bookmarks, List Posts, and Spaces lookup.

Two things follow. Posts arriving through a filtered stream webhook are billed as Post reads against this cap rather than as webhook events, which is the split covered in X API webhooks. And reads that are not Post reads, including every user, DM and analytics read, do not appear in /2/usage/tweets at all. If your spend is mostly profile lookups, the Posts meter will read near zero while your balance drains.

Deduplication softens the cap more than people expect: a Post retrieved several times inside one 24-hour UTC window counts once, which X describes as a soft guarantee rather than a promise, with service outages as the stated exception. And the billing FAQ answers one question the rest of the docs dodge: failed requests are not billed, because "only successful responses that return data are billed."

#How to actually audit a bill

Given the above, a workable routine looks like this:

1. Call /2/usage/credits on a schedule and alert on prepaid_balance, not total_balance.
2. Call /2/usage/tweets?days=30 with all six fields to see which client app is burning the Post cap.
3. Tag each job with its own counter in your own code, because X will not attribute dollars to a route for you.
4. Set a spending limit per billing cycle in the Console, which blocks requests when reached, before you run anything in a loop.

Step three is the one people skip and regret. The deduplication window and the per-resource rate card mean two jobs reading overlapping data cost less than the sum of their parts, so a local estimate drifts from the invoice. The Console is the reconciliation surface. The API is the alarm.

#When metering is the wrong problem

If you are running a data pipeline, a dashboard, or anything reading Posts at volume, these endpoints are the difference between a surprise and a budget, and the credits route is worth the extra HTTP call even though no SDK exposes it yet.

If what you want is your own account posting, replying and following on a schedule, you are metering the wrong thing. The reads you would pay for are a feed X renders for free in a browser, and the write side is where the API gets restrictive rather than merely expensive. X-Autopilot runs the browser route instead: your own logged-in session, in your own browser, on your own Mac, so the session cookie never leaves the machine and no cloud IP pool or delegate account sits in the path. That is a lower detection surface than a cloud scheduler rather than a safe one, and automating engagement through a browser is a gray area that X's automation rules address directly. The API is the sanctioned route. If you take it, meter it from day one.