Billing
You pay only on success; meta.billing and the X-Charged header say whether a call was charged. Prices: Pricing.
When you are charged
- Data returned: the listed price
- Empty search results: charged (still an answer)
- Empty trending list: free, treated as a platform error; retry
- No data from other endpoints, not found: free
- Bad parameters, platform errors, timeouts: free
- Each page of a list is billed on its own
Per-item pricing
A few endpoints (x.posts.quotes.list, x.users.mentions.list, x.posts.thread.list, x.users.search) charge per item returned: unit price × items, never below the floor or above the cap of a call, shown as "$0.0003 per item ($0.0003–0.006 a call)". The cap is held when the call starts; once the result is in, the actual amount is charged and the rest returned at once. In meta.billing, unit is item, items the count and amount what was charged. X-Max-Price compares against the cap.
X-Max-Price
Say the most you will pay for this call; above it, nothing runs and nothing is charged:
X-Max-Price: 0.01
Idempotency-Key
To retry safely, send the same Idempotency-Key. Within 24 hours the same key, Idempotency-Key and request count once; the repeat returns the first answer (Idempotent-Replayed: true). Reusing it for a different request answers 409.
Idempotency-Key: 3b8c4d2e-…
Spend caps
Set a cap per key in the console; past it, that key gets key_spend_cap_reached while other keys keep working.
Insufficient balance
A 402 insufficient_balance carries top_up_url. Scripts and agents should stop, not loop.