Back to Blog

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:

FieldMeaning
tokens_rawTokens the upstream payload would have cost
tokens_flatTokens after flattening — what you actually receive
tokens_billedWhat 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:

TierRolling 30-day top-upPer 1,000 callsPer 1M tokens
Standardnone$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