Token billing and top-up tiers, explained
What a token costs, why every call has a one-page minimum, and how top-ups lower your rate.
AgentTweet API bills for the data it returns, not for the attempt. This post walks through what that means in practice and how the rolling 30-day top-up tiers work.
You pay for tokens returned
Every successful call settles three numbers, and all three are visible in meta:
| Field | Meaning |
|---|---|
tokens_raw | Tokens the upstream payload would have cost |
tokens_flat | Tokens after flattening — what you actually receive |
tokens_billed | What this call charged you |
Flat JSON strips the noise before it reaches your prompt, which saves 78.3% of tokens against the raw payload and another 65.8% against other flattened formats. You are billed on the flat figure.
One-page minimum per call
A call that returns almost nothing still costs one page: 2,240 tokens is the minimum billing unit per call. Small responses below that floor are billed at the floor, so the effective price of a tiny lookup never falls below one page.
Failed calls are the opposite case: auth failures, upstream errors and rate limits are never billed, so a retry loop costs you nothing but latency.
Tiers follow your rolling 30-day top-ups
Your tier is decided by how much you topped up in the last 30 days, not by a subscription:
| Tier | Rolling 30-day top-up | Per 1,000 calls | Per 1M tokens |
|---|---|---|---|
| Standard | none | $0.090 | $0.040179 |
| Volume | $100 | $0.075 | $0.033482 |
| Bulk | $1,000 | $0.058 | $0.025893 |
That is 10%–16% below TwittrAPI market reference prices, and the gap widens as volume grows. Top up once and the tier applies for the whole rolling window — no plan to cancel, and the balance itself never expires.
Check live rates yourself
Rates can move, so the source of truth is the pricing endpoint:
curl 'https://api.skilltweet.com/v1/pricing' \
-H 'X-API-KEY: $AGENTTWEET_API_KEY'It returns your current tier, the per-token price and the top-up needed for the next tier. The pricing page shows the same numbers next to the TwittrAPI reference, and Add balance is where you top up.
Where to go next
- Make your first request shows the same accounting fields in a live response.
- Monitors and webhooks covers the one place where cost is a flat monthly plan instead of tokens.