Claude API Usage Alerts and Notifications Setup

If you're integrating the Claude API into a product, the question isn't whether you'll eventually hit an unexpected usage spike — it's whether you'll find out about it before your invoice does. Setting up usage alerts means defining thresholds for tokens, requests, or spend, and wiring up a notification (email, Slack, webhook) that fires automatically when those thresholds are crossed.

There's no single "enable alerts" toggle for this because the raw Claude API doesn't ship with built-in notification infrastructure — it returns usage data per request, but turning that into alerts is something you build on top. This guide covers what to track, where the usage data comes from, and a practical setup you can deploy in under an hour.

What usage data Claude API responses actually give you

Every Messages API response includes a usage object with token counts for that specific call:

{
  "id": "msg_01...",
  "usage": {
    "input_tokens": 512,
    "output_tokens": 178
  }
}

This is the raw material for any alerting system. On its own it tells you nothing about trends — you need to aggregate it over time, per API key, or per customer/project, and compare against thresholds you define. The three signals most teams care about are:

• Token volume — input + output tokens per hour/day, often as a proxy for cost
• Request volume — calls per key, useful for catching runaway loops or bot traffic
• Error/429 rate — a spike usually means you're near a rate limit or a client is retrying aggressively

If you're running Claude access through SubToAPI, each request through /v1/messages carries this same usage metadata, plus it's attributable to a specific application key (sub_live_...), which makes per-key aggregation straightforward without parsing raw Anthropic account logs.

Step 1: Log usage on every request

Don't try to compute alerts from the provider's dashboard after the fact — capture usage at the point of the call. A minimal wrapper:

async function callClaude(messages, apiKeyLabel) {
  const res = await fetch('https://api.subtoapi.app/v1/messages', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SUBTOAPI_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-5',
      max_tokens: 1024,
      messages,
    }),
  });

  const data = await res.json();

  await db.usageLog.insert({
    keyLabel: apiKeyLabel,
    inputTokens: data.usage.input_tokens,
    outputTokens: data.usage.output_tokens,
    timestamp: new Date(),
  });

  return data;
}

This gives you a table you can query for anything: hourly token totals, per-key spend estimates, week-over-week growth. It's cheap to run and it's the foundation every alert below depends on.

Step 2: Define thresholds that actually matter

Avoid a single global "too much usage" alert — it's either too noisy or too late. Set at least three tiers:

1. Soft warning (e.g., 70% of your expected daily token budget) — informational, no action needed
2. Hard threshold (e.g., 100%) — notify the team, check for abuse or a misbehaving prompt loop
3. Emergency threshold (e.g., 3x normal daily volume) — page someone, consider disabling the key temporarily

If you have multiple customers or environments behind one Claude integration, scope thresholds per key rather than account-wide. A single noisy test environment shouldn't trigger the same alert as a production spike.

Step 3: Wire up the notification

A simple cron job comparing aggregated usage against thresholds and posting to Slack covers most cases:

import fetch from 'node-fetch';

async function checkUsageAndAlert() {
  const totals = await db.usageLog.sumTokensLast24h();

  for (const [keyLabel, tokens] of Object.entries(totals)) {
    const threshold = thresholds[keyLabel] || DEFAULT_THRESHOLD;

    if (tokens > threshold) {
      await fetch(process.env.SLACK_WEBHOOK_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          text: `⚠️ Claude usage alert: ${keyLabel} used ${tokens.toLocaleString()} tokens in the last 24h (threshold: ${threshold.toLocaleString()})`,
        }),
      });
    }
  }
}

Run this every 15–30 minutes via cron, a scheduled serverless function, or your existing job scheduler. The latency between a spike happening and you hearing about it is the whole point of setting this up — don't let it run once a day.

Step 4: Separate cost alerts from rate-limit alerts

Token/cost thresholds and rate-limit (429) alerts solve different problems and should be handled separately. A cost alert tells you "this is getting expensive." A 429 spike tells you "something is about to break for users right now." Track your error rate independently:

if (res.status === 429) {
  await incrementCounter('claude_429_count');
}

If that counter crosses a short-window threshold (e.g., more than 10 in five minutes), fire an immediate notification — this one should probably page someone rather than sit in a Slack channel.

Step 5: Watch per-seat and team usage separately

If multiple team members or services share Claude access, aggregate usage breaks down fast unless you track it per application key. With team seats on SubToAPI, each member or service can get its own key under one billing plan, which means your usage logging table (from Step 1) can group cleanly by keyLabel without extra bookkeeping. This is also what makes it realistic to set per-key thresholds instead of one blunt account-wide number — see /docs/messages for the exact response shape the usage object comes in, and /pricing for how seats are structured if you're setting this up across a team.

Keep the alerting logic outside your main request path

One mistake worth avoiding: don't block or slow down the actual Claude call while checking thresholds. Log usage asynchronously (fire-and-forget or queue it) and run threshold checks on a separate schedule. Usage alerting should never add latency to a user-facing request — see /docs/streaming if you're already streaming responses and want to keep that path untouched.

questions

Does the Claude API have native usage alerts built in? No. The API returns a usage object with token counts per response, but turning that into threshold-based notifications requires you to log and aggregate it yourself, then connect it to email, Slack, or a paging tool.

What's the minimum setup to get useful alerts? Log input_tokens and output_tokens from every response into a database table keyed by API key, then run a scheduled job every 15–30 minutes that compares rolling totals against a threshold and posts to Slack if exceeded.

Should rate-limit alerts and cost alerts use the same threshold logic? No — treat them separately. Cost/token alerts are about daily or weekly trends and can tolerate delay; 429 rate-limit spikes indicate an active problem and should trigger faster, higher-urgency notifications over a short time window.