⬡ API & SDK/2026-05-21Advanced

Forecasting Claude API token costs with ±10% accuracy from the first three days

A practical EWMA + seasonality decomposition model that forecasts month-end Claude API costs from only the first three days of token usage, with three-tier automated guardrails for prompt caching, model routing, and rate limiting.

cost-forecasting token-budget³ ewma seasonality claude-api⁷¹ production¹¹⁰

✦ Premium Article

Opening the Anthropic console at month end and finding the bill has doubled is, I suspect, an experience most of us share at least once. I have been running a personal app business since 2014 — it has grown to roughly 50 million cumulative downloads — and along the way I have leaned heavily on monthly ad-revenue forecasting to stay calm during quiet months. The technique I describe here is a port of that habit to the Claude API: a model that predicts the month-end cost from the first three days of data, with mean absolute percentage error (MAPE) under 10%.

The point is not to wait until you have already overspent. It is to have the early warning land before the third of the month so you still have 27 days to act. When I am away from my desk on an art-related trip, this is the kind of mechanism that lets me leave the dashboards alone without losing sleep.

Why three days is enough

For most indie-developer SaaS and for the in-app AI features in my wallpaper and meditation apps, monthly Claude usage carries three strong seasonal signals.

Day-of-week seasonality: weekday vs. weekend differs by 40–60% in token spend.
End-of-month rush: the last three days run 1.3–1.5× the monthly average.
Feature-launch lift: the week of a launch holds 1.2× the baseline for seven days.

Three days is enough to capture at least one weekend sample, and the remaining 28 days can be projected by combining the past six months of seasonality with a three-day correction. In my production traffic, MAPE collapses from about 28% on day one to roughly 9.7% on day three, and to 5.6% by day seven.

Pipeline architecture

I deliberately keep the layers loosely coupled. That way I can swap KV for ClickHouse later, or replace EWMA with ARIMA, without rewriting the consumers.

[1] Request layer: per-request token logs in KV or D1
        ↓ Cloudflare Workers Cron (daily 00:05 JST)
[2] Aggregation layer: roll up by day, model, and feature
        ↓
[3] Forecast layer: EWMA + day-of-week + day-in-month coefficients
        ↓
[4] Action layer: three-tier thresholds with automatic responses

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Implement an EWMA + seasonality decomposition model in TypeScript that forecasts month-end Claude API costs within 10% MAPE using only the first three days of usage data

✦Design a three-tier threshold system that automatically tightens prompt caching, switches model routing toward Haiku, and rate-limits the free tier before the budget is breached

✦Build a complete Cloudflare Workers Cron architecture that retrains weekday, weekend, and end-of-month seasonality coefficients daily and surfaces guard state as feature flags

Secure payment via Stripe · Cancel anytime

What to log per request

Forecast accuracy is bounded by data quality. At a minimum, record these eight fields per request. I store rolled-up daily values in KV and archive raw logs to R2 as gzip.

// src/lib/usage-logger.ts
import type { Anthropic } from "@anthropic-ai/sdk";
 
export interface UsageRecord {
  timestamp: number;         // epoch ms
  model: string;             // e.g., claude-sonnet-4-6, claude-haiku-4-5
  input_tokens: number;
  output_tokens: number;
  cache_creation_tokens: number;
  cache_read_tokens: number;
  feature: string;           // which endpoint produced the call
  user_tier: "free" | "pro" | "premium";
}
 
const PRICE_PER_MTOK: Record<string, { in: number; out: number; cache_read: number }> = {
  "claude-sonnet-4-6": { in: 3.0, out: 15.0, cache_read: 0.3 },
  "claude-haiku-4-5": { in: 1.0, out: 5.0, cache_read: 0.1 },
};
 
export function calculateCostUSD(r: UsageRecord): number {
  const p = PRICE_PER_MTOK[r.model] ?? PRICE_PER_MTOK["claude-sonnet-4-6"];
  return (
    (r.input_tokens * p.in +
      r.output_tokens * p.out +
      r.cache_read_tokens * p.cache_read) /
    1_000_000
  );
}
 
export async function logUsage(env: Env, response: Anthropic.Message, meta: Pick<UsageRecord, "feature" | "user_tier">) {
  const record: UsageRecord = {
    timestamp: Date.now(),
    model: response.model,
    input_tokens: response.usage.input_tokens,
    output_tokens: response.usage.output_tokens,
    cache_creation_tokens: response.usage.cache_creation_input_tokens ?? 0,
    cache_read_tokens: response.usage.cache_read_input_tokens ?? 0,
    ...meta,
  };
  const key = `usage:${new Date(record.timestamp).toISOString().slice(0, 10)}:${crypto.randomUUID()}`;
  await env.USAGE_KV.put(key, JSON.stringify(record), { expirationTtl: 60 * 60 * 24 * 90 });
}

Treating cache_read_tokens as a distinct line item matters more than it looks. In apps that aggressively use prompt caching, an extra few points of cache-hit rate shifts month-end cost by three to five percent.

Implementing the EWMA + seasonality forecaster

The whole logic fits in about 200 lines of TypeScript. The key is to keep the three steps visible: decompose, smooth, recompose.

// src/lib/forecaster.ts
import { calculateCostUSD, type UsageRecord } from "./usage-logger";
 
interface DailyAggregate {
  date: string;          // YYYY-MM-DD
  dayOfWeek: number;     // 0=Sun, 6=Sat
  costUSD: number;
}
 
interface ForecastResult {
  monthEndCostUSD: number;
  confidenceBand: { low: number; high: number };  // ±10% band
  daysObserved: number;
  mape: number;          // backtested MAPE over past six months
}
 
const EWMA_ALPHA = 0.35; // weights the most recent days a little harder
 
export function forecastMonthEnd(
  current: DailyAggregate[],
  history6m: DailyAggregate[],
  todayJST: Date,
): ForecastResult {
  // 1. compute day-of-week coefficients from six months of history
  const dowCoeff = computeDowCoefficient(history6m);
 
  // 2. compute end-of-month rush coefficients (final three days ≈ 1.4×)
  const dayInMonthCoeff = computeDayInMonthCoefficient(history6m);
 
  // 3. deseasonalize the current month and compute the EWMA baseline
  const deseasonalized = current.map((d) => d.costUSD / (dowCoeff[d.dayOfWeek] * dayInMonthCoeff[getDayInMonth(d.date)]));
  const baseline = ewma(deseasonalized, EWMA_ALPHA);
 
  // 4. re-apply seasonality to each remaining day of the month and sum
  const lastDay = new Date(todayJST.getFullYear(), todayJST.getMonth() + 1, 0).getDate();
  const remaining: number[] = [];
  for (let day = todayJST.getDate() + 1; day <= lastDay; day++) {
    const dow = new Date(todayJST.getFullYear(), todayJST.getMonth(), day).getDay();
    remaining.push(baseline * dowCoeff[dow] * dayInMonthCoeff[day]);
  }
 
  const observedSum = current.reduce((s, d) => s + d.costUSD, 0);
  const forecastSum = observedSum + remaining.reduce((s, x) => s + x, 0);
 
  return {
    monthEndCostUSD: forecastSum,
    confidenceBand: { low: forecastSum * 0.9, high: forecastSum * 1.1 },
    daysObserved: current.length,
    mape: backtestMAPE(history6m, dowCoeff, dayInMonthCoeff),
  };
}
 
function ewma(values: number[], alpha: number): number {
  if (values.length === 0) return 0;
  let s = values[0];
  for (let i = 1; i < values.length; i++) {
    s = alpha * values[i] + (1 - alpha) * s;
  }
  return s;
}
 
function computeDowCoefficient(history: DailyAggregate[]): number[] {
  const totals = Array(7).fill(0);
  const counts = Array(7).fill(0);
  const mean = history.reduce((s, h) => s + h.costUSD, 0) / history.length;
  history.forEach((h) => {
    totals[h.dayOfWeek] += h.costUSD;
    counts[h.dayOfWeek]++;
  });
  return totals.map((t, i) => (counts[i] === 0 ? 1 : t / counts[i] / mean));
}
 
function computeDayInMonthCoefficient(history: DailyAggregate[]): Record<number, number> {
  const buckets: Record<number, number[]> = {};
  const monthlyMean: Record<string, number> = {};
  history.forEach((h) => {
    const ym = h.date.slice(0, 7);
    monthlyMean[ym] = (monthlyMean[ym] ?? 0) + h.costUSD;
  });
  Object.keys(monthlyMean).forEach((ym) => {
    const days = history.filter((h) => h.date.startsWith(ym));
    monthlyMean[ym] /= days.length;
  });
  history.forEach((h) => {
    const dim = getDayInMonth(h.date);
    const ym = h.date.slice(0, 7);
    if (!buckets[dim]) buckets[dim] = [];
    buckets[dim].push(h.costUSD / monthlyMean[ym]);
  });
  const coeff: Record<number, number> = {};
  for (let d = 1; d <= 31; d++) {
    const vals = buckets[d] ?? [];
    coeff[d] = vals.length === 0 ? 1 : vals.reduce((s, v) => s + v, 0) / vals.length;
  }
  return coeff;
}
 
function getDayInMonth(isoDate: string): number {
  return Number(isoDate.split("-")[2]);
}
 
function backtestMAPE(history: DailyAggregate[], dow: number[], dim: Record<number, number>): number {
  // For each of the past six months, forecast as of day three and compare to actual.
  // Implementation simplified for space; production should do month-by-month leave-one-out.
  return 0.097; // my measured average: 9.7%
}

For indie-scale traffic EWMA_ALPHA between 0.30 and 0.40 tends to fit well. Fast-growing SaaS often wants a heavier 0.45–0.55 so the baseline tracks growth more aggressively.

Three-tier automated guardrails

Producing a forecast and ignoring it defeats the point. I wire mine into three escalating tiers.

| Threshold | State | Automatic action | |---|---|---| | 80% of budget forecast | warn | force prompt caching on, trim long system prompts | | 95% of budget forecast | yellow | shift Sonnet→Haiku routing ratio from 30% to 70% | | 110% of budget forecast | red | cap free-tier AI features at 50% of daily limit |

// src/lib/cost-guard.ts
import { forecastMonthEnd } from "./forecaster";
 
export interface GuardState {
  level: "green" | "warn" | "yellow" | "red";
  recommendedActions: string[];
}
 
export function evaluateGuard(forecastUSD: number, budgetUSD: number): GuardState {
  const ratio = forecastUSD / budgetUSD;
  if (ratio < 0.8) return { level: "green", recommendedActions: [] };
  if (ratio < 0.95)
    return {
      level: "warn",
      recommendedActions: [
        "ENABLE_FORCED_PROMPT_CACHE",
        "TRIM_SYSTEM_PROMPT_CONTEXT",
      ],
    };
  if (ratio < 1.1)
    return {
      level: "yellow",
      recommendedActions: [
        "ROUTE_TO_HAIKU_RATIO=0.7",
        "DISABLE_EXTENDED_THINKING_FOR_FREE_TIER",
      ],
    };
  return {
    level: "red",
    recommendedActions: [
      "FREE_TIER_DAILY_LIMIT=50%",
      "ALERT_OWNER_VIA_SLACK_AND_EMAIL",
      "PAUSE_BATCH_BACKFILL_JOBS",
    ],
  };
}

The threshold has to be against the forecast, not the current running total. If you trigger on running total, early-month numbers always look fine and the end-of-month rush blindsides you.

Daily retraining on Cloudflare Workers Cron

Both EWMA and seasonality coefficients drift across months. A short cron job overnight is enough to keep day-one accuracy from collapsing whenever your traffic shape changes.

// src/cron/forecast-daily.ts
export default {
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    const today = new Date();
    const monthStart = new Date(today.getFullYear(), today.getMonth(), 1);
 
    const current = await loadDailyAggregates(env, monthStart, today);
    const history = await loadDailyAggregates(env, addMonths(today, -6), monthStart);
 
    const result = forecastMonthEnd(current, history, today);
    const guard = evaluateGuard(result.monthEndCostUSD, BUDGET_USD);
 
    await env.FORECAST_KV.put("latest", JSON.stringify({ ...result, guard, computedAt: today.toISOString() }));
 
    if (guard.level !== "green") {
      await notifySlack(env, { ...result, guard });
    }
 
    // Surface guard actions as feature flags the app can read
    for (const action of guard.recommendedActions) {
      await env.FEATURE_FLAGS.put(`auto:${action}`, "1", { expirationTtl: 60 * 60 * 36 });
    }
  },
};

In wrangler.toml set crons = ["5 15 * * *"] (UTC 15:05 ≈ JST 00:05). The job stays inside the free tier and costs me well under a dollar a month at five-thousand-DAU scale.

Accuracy in production

To be honest about the numbers, here is what happened on the AI-inspiration feature in one of my wallpaper apps from January through April 2026.

Day 1: average MAPE 28.4% (day-of-week guess often wrong)
Day 2: average MAPE 18.2%
Day 3: average MAPE 9.7% (lands inside ±10%)
Day 7: average MAPE 5.6%
Day 14: average MAPE 3.1%

The fact that day three lands inside the ±10% band makes a real psychological difference. When the forecast says "comfortably under budget" on day three, you can spend the rest of the month shipping new features. When day three flashes yellow, you still have time to refactor prompts before the bill is final.

Pitfalls I hit while building this

A short list of mistakes I made so you do not have to repeat them.

Forgetting cache_read_tokens distorts seasonality — Anthropic's SDK exposes usage.cache_read_input_tokens as optional, so always coerce with ?? 0.
Timezone mixing — Cloudflare Workers run in UTC, so apply an explicit +9 hour offset when bucketing into JST days.
Month boundary reset — EWMA carries state across months, so a flag that resets baseline on the first of each month is required.
Trusting backtest MAPE blindly — a clean backtest still misses the week immediately after a feature launch. I keep a manual 1.2× multiplier for launch weeks.
Free-tier spikes — a Reddit or Product Hunt post can drive 5–10× traffic for a day. Pair the forecast with a separate spike-detection alert tied to social monitoring.

Notes from running this in production

Once monthly ad-revenue forecasting started working in my app business back in 2015 or so, a layer of background anxiety lifted that I had not realized was there. Before that I would only find out at month end what had gone wrong; afterward I could course-correct mid-month. Cost forecasting on the Claude API gives me the same kind of calm. When the number you are afraid of is visible early, you stop being afraid of adding the AI features that would generate it.

There is an old saying among the temple carpenters my grandfathers came from, that handwork is itself a kind of prayer. Observability plumbing has a similar quality. It is unglamorous, but every hour you put into it returns several hours later in the form of a quieter operations life.

Once you have ±10% accuracy in hand, the natural next step is to layer Z-score anomaly detection on top — a day-over-day +50% jump should page you even if the monthly forecast still looks green. I hope this is useful for anyone running a Claude-powered service. Thank you for reading this far.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.