Claude API Usage Quota Per User Tracking Guide

Claude API usage quota per user tracking

If you're building a product on top of Claude and multiple users or customers share your backend, you need a way to answer two questions: how much has each user consumed, and when do they need to be cut off or upgraded. Anthropic's API gives you token counts on every response, but it does not give you per-user quotas, resets, or dashboards — that part is entirely on you to build.

This article covers the two realistic paths: rolling your own tracking layer on top of raw token counts, or using a gateway that issues per-user API keys and tracks usage automatically. Both work; the right choice depends on how many users you have and how much billing logic you actually want to maintain.

Why Claude doesn't track this for you

Anthropic's API is stateless per request. Every call to /v1/messages returns a usage object with input_tokens and output_tokens, but that's scoped to the single request — there's no concept of "user A" or "team B" unless you build it yourself. If you're serving five internal tools, that's manageable with a spreadsheet. If you're serving hundreds of end users with different plans, you need a real tracking layer.

Option 1: Build your own per-user tracking

The basic pattern is: wrap every Claude call, capture the usage object, attribute it to a user ID, and persist it.

async function callClaude(userId, messages) {
  const response = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: {
      "x-api-key": process.env.ANTHROPIC_API_KEY,
      "anthropic-version": "2023-06-01",
      "content-type": "application/json",
    },
    body: JSON.stringify({
      model: "claude-sonnet-4-5",
      max_tokens: 1024,
      messages,
    }),
  });

  const data = await response.json();
  const { input_tokens, output_tokens } = data.usage;

  await db.usage.create({
    userId,
    inputTokens: input_tokens,
    outputTokens: output_tokens,
    timestamp: new Date(),
  });

  return data;
}

From there you need to decide:

• Quota unit: tokens, requests, or a converted cost figure (tokens × model price).
• Reset window: daily, monthly, rolling 30 days — each has different query logic.
• Enforcement point: check the quota before calling Claude (to avoid wasted spend on requests you'll reject) or after (simpler, but you eat the cost of overages).
• Streaming: if you use streaming responses, the usage data arrives at the end of the stream, in the final message_delta event, not up front — your tracking code has to handle that event type separately from non-streaming calls.

A minimal quota check before calling Claude looks like this:

async function checkQuota(userId, limit) {
  const used = await db.usage.sumTokens(userId, "currentMonth");
  if (used >= limit) {
    throw new Error("Usage quota exceeded for this billing period");
  }
}

This works fine for a handful of users. Once you have real customers on different plans, you'll also need: a cron job to reset counters, a way to show users their own usage, overage billing or hard cutoffs, and probably a way to split usage by feature (chat vs. document analysis vs. tool calls). That's a non-trivial amount of infrastructure for something that's adjacent to your actual product.

Option 2: Per-user API keys with built-in usage tracking

An alternative is to not build the attribution layer yourself at all. If each user or team gets its own API key, usage tracking becomes a lookup instead of a database you maintain.

This is the model SubToAPI uses: instead of one shared Anthropic key routed through your own logic, you issue separate sub_live_... keys per user, team, or project from your SubToAPI dashboard. Every request made with a given key is logged against that key automatically — tokens in, tokens out, request count, timestamps — without you writing any tracking code.

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Summarize this ticket."}]
  }'

Swap in a different key per user and you get per-user usage history in the dashboard for free — no reset cron, no attribution bugs, no reconciliation between your database and your Anthropic invoice. For teams, this maps directly onto seats: each seat gets its own key and its own usage trail, which is useful if you're billing by seat yourself (Solo is €9 for a single key, Team is €19/seat, Scale is €49/seat with higher limits — see /pricing for the breakdown).

This doesn't replace application-level business logic — you still decide what happens when a user hits a soft limit, and whether to show them a warning or block further calls. But it removes the token-accounting layer entirely, which is usually the most error-prone part of building this yourself (off-by-one reset dates, missed streaming events, double-counting retries).

If you're evaluating this route, /docs/quickstart walks through creating your first key and making a request, and /docs/messages covers the request/response shape in detail, including where usage data shows up in both streaming and non-streaming responses.

Choosing between the two

Build your own tracking if:

• You have a small, fixed set of internal users.
• You already have billing infrastructure and just need the raw numbers.
• Your quota logic is tightly coupled to other parts of your product (e.g., usage gates a non-AI feature too).

Use per-key tracking (SubToAPI or similar) if:

• You're serving external customers and need clean per-customer usage data fast.
• You don't want to maintain a token-counting pipeline as a side project.
• You want streaming, tool use (/docs/tools), and usage metadata handled consistently without writing separate code paths for each.

Either way, decide on your quota unit and reset window before you write any code — retrofitting that decision after you have real usage data is the painful part, not the initial implementation.

questions

Does the Claude API expose per-user usage natively? No. Every response includes a usage object with input and output token counts, but it's per-request only — there's no built-in concept of users, teams, or quotas. You have to attribute usage yourself or use a layer that does it for you.

What's the easiest way to track usage for streaming responses? Usage data in streaming responses arrives in the final message_delta event, not at the start. Your tracking code needs a separate handler for streaming vs. non-streaming calls, or you need a platform that already normalizes this, like SubToAPI's /docs/streaming endpoint.

Can I give each user their own API key instead of building a database? Yes — issuing one key per user or team is often simpler than building token-attribution logic yourself. SubToAPI generates sub_live_... keys per user/seat and tracks usage against each key automatically; see /signup to try it on a free trial.