Setting a Token Budget Per Free User: Balancing AdMob Revenue Against AI Feature Cost

Reconstruct true cost from four usage_metadata fields

Before you can hold a budget you need the exact cost of one call. Four fields on the response's usage_metadata give you that.

That fourth row is where I lost money first. More on that below.

Keep the call wrapper in exactly one place. If parts of your app reach for the SDK directly, the ledger will leak.

# gemini_budget.py
from dataclasses import dataclass
from google import genai
 
client = genai.Client()
 
# Effective rates (JPY per 1M tokens), backed out of my own invoice. Revisit quarterly.
PRICE_JPY_PER_MTOK = {
    "input": 45.0,
    "cached": 11.0,
    "output": 360.0,
    "thoughts": 360.0,
}
 
 
@dataclass
class Usage:
    fresh_input: int
    cached_input: int
    output: int
    thoughts: int
 
    @property
    def cost_jpy(self) -> float:
        p = PRICE_JPY_PER_MTOK
        return (
            self.fresh_input * p["input"]
            + self.cached_input * p["cached"]
            + self.output * p["output"]
            + self.thoughts * p["thoughts"]
        ) / 1_000_000
 
    @property
    def weighted_tokens(self) -> int:
        # Denominate the budget in input-equivalent tokens so a price change
        # does not orphan the historical ledger.
        return int(self.cost_jpy / (PRICE_JPY_PER_MTOK["input"] / 1_000_000))
 
 
def extract_usage(response) -> Usage:
    u = response.usage_metadata
    cached = getattr(u, "cached_content_token_count", 0) or 0
    thoughts = getattr(u, "thoughts_token_count", 0) or 0
    prompt = u.prompt_token_count or 0
    output = u.candidates_token_count or 0
    return Usage(
        fresh_input=max(prompt - cached, 0),
        cached_input=cached,
        output=output,
        thoughts=thoughts,
    )

The weighted_tokens indirection matters. A budget held in currency breaks continuity every time a rate changes or you swap models. Held in input-equivalent tokens, you only swap the price table.

Hold the cap in stages, not as a wall

Cutting a feature off the instant it hits 100% is indistinguishable, from the user's side, from the feature being broken. I run a three-step ladder instead.

The downgrade at 70% exists to slow the burn rate itself. The lighter model costs roughly a quarter as much per call, so the remaining 30% of budget buys close to four times the calls it otherwise would. The share of users who reach the hard cap fell from 3.1% to 0.4% for me.

# budget_guard.py
SOFT_CAP = 0.70
MONTHLY_BUDGET_TOKENS = 7_500
 
MODEL_LADDER = {
    "normal": ("gemini-3-pro", {"thinking_level": "high"}),
    "reduced": ("gemini-flash-latest", {"thinking_level": "low"}),
}
 
 
class BudgetExceeded(Exception):
    pass
 
 
def select_tier(spent_tokens: int) -> str:
    ratio = spent_tokens / MONTHLY_BUDGET_TOKENS
    if ratio >= 1.0:
        raise BudgetExceeded(f"budget exhausted: {ratio:.0%}")
    return "reduced" if ratio >= SOFT_CAP else "normal"
 
 
def generate_for_user(ledger, user_id: str, prompt: str):
    spent = ledger.spent_this_period(user_id)
    tier = select_tier(spent)              # over 100% raises before we spend
    model, config = MODEL_LADDER[tier]
 
    response = client.models.generate_content(
        model=model, contents=prompt, config=config
    )
    usage = extract_usage(response)
    ledger.record(user_id, usage.weighted_tokens, usage.cost_jpy, tier)
    return response.text, tier

select_tier before the call, ledger.record after. Keep that order. Reversed, every user pays for exactly one over-budget call before the guard engages. For one user that is rounding error; on the day a few hundred users hit the ceiling together, it is not.

Set the project-level spend cap on the Gemini API side as a last line of defense as well. Your ledger cannot see calls that happen outside your ledger.

Abuse shows up as one concentration ratio

Averages hide abuse. The single number I watch is the share of total spend consumed by the top 1% of users.

In a healthy app it sits somewhere around 8–15%. Above 20%, there is an automated client or someone stuck in a loop with the feature.

# concentration.py
import statistics
 
 
def top_share(spend_by_user: dict[str, float], top_pct: float = 0.01) -> float:
    values = sorted(spend_by_user.values(), reverse=True)
    if not values:
        return 0.0
    k = max(1, int(len(values) * top_pct))
    return sum(values[:k]) / sum(values)
 
 
def anomaly_report(spend_by_user: dict[str, float]) -> dict:
    values = list(spend_by_user.values())
    median = statistics.median(values)
    outliers = {
        uid: v for uid, v in spend_by_user.items()
        if median > 0 and v > median * 20
    }
    return {
        "top1_share": round(top_share(spend_by_user), 3),
        "median_tokens": median,
        "outlier_users": sorted(outliers, key=outliers.get, reverse=True)[:20],
    }

The 20x-the-median threshold has no principled basis. It is simply where, in my data, legitimate power users separated from automated clients. Plot the histogram on your own logs before you pick a number.

I run this daily and alert only on days when top1_share clears 20%. A report that arrives every morning stops being read by Wednesday.

Four places I was counting wrong

For about two months, my ledger and my invoice disagreed by roughly 10%. Every cause was on the accounting side.

1. Thinking tokens were missing

thoughts_token_count is not part of candidates_token_count. On a thinking-enabled model, a large fraction of your real output cost lives in those thinking tokens. That single omission left my ledger about 7% under.

2. Retries were double-counted

A call that returned 429 and was retried can still carry usage_metadata on the failed attempt. I wrote it into the wrapper contract: record exactly one successful response. The reverse case remains unresolved — a call that timed out on my side may still have been billed, and it never reaches the ledger at all.

3. Cache hits were priced as fresh input

I was multiplying prompt_token_count by the input rate without subtracting cached_content_token_count. The more effectively a feature used caching, the more the ledger overstated it — and the less the savings showed up. I spent a while puzzled by that.

4. The reset boundary drifted by nine hours

The ledger reset at the start of the UTC month while I read the invoice in Japan time. Nine hours a month, the two numbers described different periods. Aligning both to JST brought the gap under 1%.

Where to start today

None of this needs to be built at once. I recommend this order.

1. Funnel every call through one wrapper and simply log the four usage_metadata fields. No budget enforcement yet.
2. After a week, compute the top-1% share and the median from those logs, and look at your actual distribution.
3. Only then choose the budget and the thresholds — and ship the soft cap first.

Do it in the other order and the limit will be either far too tight or meaningless. My first attempt was a groundless "ten calls a day," and it throttled legitimate users before it touched anyone else.

Look at the numbers, then decide. Obvious enough, and yet when the topic turns to cost, the ceiling is always the first thing we want to pick.