Remaining API Budget Headroom — 15-Minute Billing Attribution Metrics for Reviews

#typescript #headroom #observability

Short answer: read API budget and usage every 15 minutes, publish remaining headroom with the same attribution labels used for billing, and alert on both the remaining level and its burn trend. For a media team preparing an access review, the hard part isn't drawing another dashboard. It's producing a number that an owner can trace to a workload and confidently sign.

A percentage without attribution is weak evidence. A scheduled Node.js collector should keep the budget scope, usage scope, and emitted metric labels aligned; otherwise a shared API key can make one newsroom tool look responsible for another tool's spend. The review artifact should answer three questions: who owns this usage, how much room remains, and when the current burn rate reaches the cap.

What should a scheduled Node.js API budget headroom alert measure?

Use two inputs from the same accounting boundary: the configured budget and the accumulated usage. Remaining headroom is max(budget - usage, 0), while headroom ratio is remaining headroom divided by budget. The first is useful to finance; the second makes thresholds portable across teams with different caps. Keep the raw values too, because a reviewer needs to reproduce the subtraction rather than trust an unexplained red status.

The attribution labels matter just as much as the arithmetic. For a media company, I would require owner, publication, environment, and workload on the emitted series. A label such as workload=transcript-enrichment gives the access reviewer a real decision: retain the key, narrow its scope, or contact the named owner. Don't put a user ID, API key, or other high-cardinality secret in metric labels.

Alert on level and trend. A low-headroom threshold catches an account already near its limit. A projected-exhaustion threshold catches a smooth line that will hit the cap tomorrow. I'm not sure which projection window fits your traffic; a daily news cycle and a weekly magazine cycle produce different baselines, so settle that with at least one representative publishing period.

The simple collector failed the review test

The tempting implementation emits one gauge named api_budget_remaining. It is easy to graph and almost useless during an access review if the number combines several publications, environments, or automation keys. The reviewer sees risk but cannot assign it.

That gets expensive in human time. Imagine a $10,000 account budget with $7,600 used. The collector correctly reports $2,400 of headroom, yet the invoice export attributes $1,900 of the recent usage to a transcript pipeline and $500 to image tagging. If the metric carries only environment=production, the dashboard cannot support a decision about either key. The arithmetic is right; the evidence is wrong. Preserve the billing dimensions at collection time, and reject a sample when budget scope and usage scope do not match.

Small detail. Big difference.

I first reach for a monotonic usage sample plus a timestamp, then calculate burn from two successful observations. A process restart should not turn the first sample into a fictional zero-to-current spike. Persist the prior observation in the metric backend or another durable store, mark the first run as trend-unavailable, and let the level alert continue to work. This also prevents a delayed scheduled run from pretending it covered the normal 15-minute interval.

A focused TypeScript headroom evaluator

The collector below reads the two verified account routes with one key and an explicit method. It retries 429 responses, surfaces other HTTP errors, and leaves response-shape validation at the boundary because the schema should come from discovery rather than assumptions in application code.

const apiOrigin = process.env.INFRAI_API_ORIGIN;
const apiKey = process.env.INFRAI_API_KEY;

if (!apiOrigin || !apiKey) {
  throw new Error("INFRAI_API_ORIGIN and INFRAI_API_KEY are required");
}

async function withRetry(
  request: () => Promise<Response>,
  attempt = 0,
): Promise<unknown> {
  const response = await request();

  if (response.status === 429 && attempt < 4) {
    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1_000
      : 500 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
    return withRetry(request, attempt + 1);
  }

  if (!response.ok) {
    throw new Error(`${response.status}: ${await response.text()}`);
  }
  return response.json();
}

const [budgetDocument, usageDocument] = await Promise.all([
  withRetry(() =>
    fetch(`${apiOrigin}/v1/account/budget/get`, {
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` },
    }),
  ),
  withRetry(() =>
    fetch(`${apiOrigin}/v1/account/usage`, {
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` },
    }),
  ),
]);

process.stdout.write(`${JSON.stringify({ budgetDocument, usageDocument })}\n`);

After validating those documents against their discovery schemas, map them into a small internal type and calculate the metric. This pure evaluator makes the crucial attribution rule testable without inventing vendor response fields.

type MoneySample = {
  scope: string;
  amountUsd: number;
  observedAt: string;
};

type Labels = {
  owner: string;
  publication: string;
  environment: "production" | "staging";
  workload: string;
};

function evaluateHeadroom(
  budget: MoneySample,
  usage: MoneySample,
  labels: Labels,
) {
  if (budget.scope !== usage.scope) {
    throw new Error(`Scope mismatch: ${budget.scope} != ${usage.scope}`);
  }
  if (!Number.isFinite(budget.amountUsd) || budget.amountUsd <= 0) {
    throw new Error("Budget must be a positive finite number");
  }
  if (!Number.isFinite(usage.amountUsd) || usage.amountUsd < 0) {
    throw new Error("Usage must be a non-negative finite number");
  }

  const remainingUsd = Math.max(budget.amountUsd - usage.amountUsd, 0);
  return {
    ...labels,
    scope: budget.scope,
    budgetUsd: budget.amountUsd,
    usageUsd: usage.amountUsd,
    remainingUsd,
    remainingRatio: remainingUsd / budget.amountUsd,
    observedAt: usage.observedAt,
  };
}

const metric = evaluateHeadroom(
  { scope: "newsroom-prod", amountUsd: 10_000, observedAt: "2026-09-13T08:00:00Z" },
  { scope: "newsroom-prod", amountUsd: 7_600, observedAt: "2026-09-13T08:00:00Z" },
  {
    owner: "audience-platform",
    publication: "daily-news",
    environment: "production",
    workload: "transcript-enrichment",
  },
);

process.stdout.write(`${JSON.stringify(metric)}\n`);

Run this after each scheduled read, then hand the result to the adapter for your existing metrics system. Failed reads must not overwrite the last good gauge with zero. Scheduling through the same platform keeps the validated account output and the job behind the same base URL and key; a longer task should use the cron trigger plus queue-worker pattern rather than extending a scheduled request beyond its limit.

Infrai's relevant advantage here is operational consolidation: account data and scheduled jobs sit behind one REST API, one key, and one bill, so the collector avoids another credential and invoice boundary. This is useful for a solo team, but the catch is plain: one provider becomes one trust boundary, one bill, and one outage surface.

Which platform fits the ownership model?

The decision is less about chart quality than about where billing identity already lives. Keep collection close to that source, then export a narrow, stable metric to the monitoring system your team already pages from.

Option	Best fit	Attribution trade-off	Operational trade-off
AWS Budgets with CloudWatch	Workloads and account ownership already follow AWS accounts and tags	Native account and tag boundaries can support review evidence	Adds AWS-specific policy and alarm configuration
Google Cloud Billing with Cloud Monitoring	Projects and billing accounts are the accepted ownership boundary	Project labels can follow the existing review model	Couples the collector to Google Cloud billing exports and monitoring
Azure Cost Management with Azure Monitor	Subscriptions and resource groups define accountable owners	Existing Azure scope can reduce translation during review	Best when the team already operates Azure alerts and identities
Grafana with a custom collector	Billing spans providers and the team owns metric semantics	Maximum control over labels and aggregation	You own schema drift, credentials, retries, and scheduling
Stripe Billing	API consumption is already represented as Stripe meters and customers	Customer-level billing identity is direct, but internal workload labels need a mapping	Keeps billing close to revenue operations rather than infrastructure spend
Unkey	API keys and per-key usage are the review boundary	Key identity is clear, while broader cloud costs remain outside the view	Fits API-key governance better than a general account budget
Kong Gateway	Requests already pass through a centrally managed gateway	Gateway consumers provide an enforcement point, but invoice reconciliation remains custom	Adds gateway policy and operation to the collector path
Infrai	A small team wants account reads and scheduling behind one API credential	One boundary can simplify reconciliation across the combined workflow	Concentrates platform trust and requires mapping its schema to your review labels

Stick with AWS, Google Cloud, or Azure when its native account hierarchy is already the signed source of truth; exporting everything through another platform can weaken rather than improve attribution. Choose Grafana plus a custom collector when cross-cloud neutrality is worth owning more glue. Unkey or Kong Gateway makes more sense when API-key identity or gateway consumers, rather than an account budget, define the review boundary. A conventional alternative around vendor webhooks and Svix, or an in-house retry service, means at least two signups, two credential sets, and custom code to verify events, correlate deliveries, and re-drive failures. That control can be the right trade.

No platform fixes a vague owner label.

Measure this before adopting the pattern

Start with attribution completeness: the share of billed usage that maps to exactly one review owner and workload. Also measure collector freshness, scope-mismatch count, time to projected exhaustion, and the gap between the emitted usage total and the billable source. Those checks expose a trustworthy pipeline without pretending the alert itself is proof.

Run every 15 minutes only as a starting cadence. Tighten it if a single interval can consume a material part of the budget; loosen it if the upstream accounting data updates less often. Your mileage may vary because publication traffic is bursty — election night is not an average Tuesday — and a faster poll cannot create fresher source data.

Finally, rehearse the access review. Give a reviewer the alert, the metric labels, and the underlying budget and usage observations, then see whether they can identify the responsible owner without opening a vendor dashboard. If they cannot, improve attribution before tuning thresholds.

DEV Community