WEIR
Get a key
Theme

X API Usage: Check Credits and the 3M Cap (2026)

How to check X API usage on pay-per-use: the console's billing pages, both usage endpoints and their fields, the 3M read cap, and a tested credit alert.


Published · Updated · 7 min read

Cover image: A low-credit alarm you can cron

You check X API usage in the Developer Console, or with two endpoints: /2/usage/credits for your balance and /2/usage/tweets for posts read.

This is for developers on the X (Twitter) pay-per-use API who don't want a 402 error to be their first warning. You get both endpoints with their fields, the monthly cap, and an alert script we ran. We run Weir, the API in Step 5.

Both calls, as X's API reference defines them:

curl "https://api.x.com/2/usage/credits" -H "Authorization: Bearer $BEARER_TOKEN"
curl "https://api.x.com/2/usage/tweets?days=30&usage.fields=project_usage,project_cap,cap_reset_day" \
  -H "Authorization: Bearer $BEARER_TOKEN"
  1. Open the consoleBilling → Credits lists your credits.
  2. Call /2/usage/creditsRead total_balance in dollars.
  3. Call /2/usage/tweetsCompare project_usage with project_cap.
  4. Alert below a floorRun a script on a schedule.

Step 1: Check X API usage in the Developer Console

The Developer Console at console.x.com is X's usage dashboard. X's console page says it tracks usage "in real-time" and shows costs per endpoint.

X's usage and billing page lists five views there:

  • Total usage: posts retrieved in the billing period.
  • By endpoint and by app: where the reads came from.
  • Cost tracking: what those reads cost so far.
  • Credit balance: the prepaid credits you have left.

X's free-credits page names Billing → Credits as where credits show up, and Billing → Payments for each transaction. We couldn't open the console ourselves, so there are no screenshots here.

The console also holds your two money controls: a spending limit and auto-recharge. Our X API 402 guide covers both, and why auto-recharge stops at $0.

Step 2: Check X API credits remaining with /2/usage/credits

GET /2/usage/credits returns your pay-per-use balance in US dollars. X's reference accepts an app bearer token or an OAuth 2.0 user token.

The response has four fields under data:

  • total_balance is what you can spend. X defines it as max(0, prepaid_balance + free_balance), so it never shows a debt.
  • prepaid_balance is the money you bought. It can go negative.
  • free_balance is what's left of unexpired free grants.
  • free_grants lists each grant's amount and expires_at, soonest first.

X's reference doesn't say whether this call itself is billed. We have no X key, so we haven't seen a live response.

Step 3: Track posts read against the 3M cap with /2/usage/tweets

Pay-per-use accounts can read 3 million posts per monthly billing cycle, says X's pricing page. Past that, X's response codes page lists a 429 whose error type ends in usage-capped.

3Mpost reads per billing cycle
90days of history, at most
$0.005per post read, as of October 2026

GET /2/usage/tweets shows how close you are. It takes a bearer token and two parameters:

  • days runs from 1 to 90 and defaults to 7.
  • usage.fields picks fields: project_usage, project_cap, cap_reset_day, daily_project_usage, daily_client_app_usage and project_id.

Divide project_usage by project_cap for the share of your cap that's gone. X's reference also lists cap_reset_day with no description; it most likely names the day your cap resets.

The count covers posts from lookup, search, streams, timelines, liked posts, bookmarks, List posts and Spaces, per X's usage and billing page.

Step 4: Alert yourself before credits run out

X's usage and billing page says to "set up balance alerts," but we couldn't find a page that says where. Here is what X does document:

  • Auto-recharge buys more credits below a trigger amount. It's a refill, not a warning.
  • A spending limit blocks requests for the rest of the billing cycle. It's a hard stop.

Pick the number that matches the stop you fear:

  • Running dry: total_balance below about a day of your spend.
  • A debt: prepaid_balance below 0, which blocks calls.
  • The cap: project_usage past 90% of project_cap.
  • Expiring free credits: the soonest expires_at in free_grants.

The warning is yours to build. This script reads a saved usage response and exits with 1 below your floor, so cron, CI or any scheduler can act on it:

import json, sys

def remaining(usage):
    data = usage["data"]
    if "total_balance" in data:  # X's /2/usage/credits, in US dollars
        return data["total_balance"], "USD"
    return data["available"], "credits"  # Weir's /v1/usage

def main(path, floor):
    with open(path, encoding="utf-8") as file:
        left, unit = remaining(json.load(file))
    status = "WARN" if left < floor else "OK"
    print(f"{status}: {left} {unit} left, floor {floor:g}")
    return 1 if status == "WARN" else 0
sys.exit(main(sys.argv[1], float(sys.argv[2])))

We ran it on 22 October 2026 against our saved Weir response from Step 5:

$ python credit_alert.py usage.json 1000
WARN: 673 credits left, floor 1000
$ python credit_alert.py usage.json 500
OK: 673 credits left, floor 500

For X, save the /2/usage/credits response instead and pass a floor in dollars, such as 5. We tested that branch only on X's documented field names.

Step 5: Check Weir usage for free with /v1/usage and /v1/limits

We run Weir, a read-only API for public X and Reddit data, so weigh this step knowing that. Its GET /v1/usage and GET /v1/limits cost nothing, and they still answer when you're out of credits.

curl https://api.weirapp.io/v1/usage -H "Authorization: Bearer $WEIR_API_KEY" > usage.json

In Claude or another MCP client, the same calls are the free get_usage and get_limits tools. We called both on 22 October 2026. get_usage returned, trimmed:

{
  "data": {
    "balance": 673,
    "reserved": 0,
    "available": 673,
    "freeGrant": { "granted": 5000, "remaining": 673, "resetsAt": "2026-11-01T00:00:00.000Z" },
    "tier": "free",
    "spendingPaused": false
  },
  "meta": { "creditsCharged": 0 }
}
  • available is balance minus what calls in flight have reserved. Alert on this one.
  • freeGrant shows this month's 5,000 free credits and when they reset.
  • spendingPaused turns true only during a refund or payment dispute.
Our free grant on 22 October 2026, from get_usage
Granted5,000
Spent4,327
Left673

get_limits returned the free tier's ceilings: 30 requests a minute, with 1 monitor and 1 webhook.

You don't have to poll at all. Every billed response carries x-credits-charged and x-credits-remaining headers, and the MCP tools copy them into meta.creditsCharged and meta.creditsRemaining. Free calls carry no remaining count, so read available from the body.

Read x-credits-remaining after each call and stop below your floor. The REST body's meta carries requestId and, on lists, nextCursor, so the charge lives only in the headers. Price a job before you run it with the X API cost calculator.

If the numbers look wrong

  • total_balance reads 0 after a top-up. Check prepaid_balance: X's pricing page says a negative balance blocks calls until you cover it.
  • Calls fail while credits remain. Check your spending limit, which blocks the rest of the cycle. X doesn't say which status code it returns.
  • A 429 that waiting won't fix. An error type ending in usage-capped means the monthly cap.

When not to use Weir

  • You need X's own numbers. Weir's meter covers Weir calls, not your X developer account.
  • You post, like or send DMs. Weir only reads, so writes need X's API.
  • You need a contract with X itself, or more than 3 million post reads a month.
  • Price per post is all that matters. TwitterAPI.io lists $0.15 per 1,000 tweets, below Weir's packs.

Weir isn't licensed by X, so access can change.

FAQ

How do I check my X API usage?

Open the Developer Console at console.x.com and look under Billing, or call GET /2/usage/tweets with your bearer token. It returns daily post counts for up to 90 days, plus your project's cap.

How do I see my X API credits remaining?

Call GET /2/usage/credits. Its total_balance field is your spendable balance in US dollars, and free_grants shows when free credits expire. The console shows the same balance under Billing → Credits.

Is there a Twitter API usage dashboard?

Yes. X's Developer Console shows total usage, usage by endpoint and by app, running cost and credit balance. X's docs list those views; we couldn't sign in to see them ourselves.

What happens when I hit the X API monthly cap?

Post reads stop for the rest of the billing cycle. X returns a 429 with a usage-capped error type, which a rate-limit wait won't clear. Our X API rate limits guide shows how to tell the two 429s apart.

Sources

All checked on 22 October 2026. We read docs.x.com as Markdown, adding .md to each URL:

Keep reading