PKM

Anthropic API — Usage Reporting & Token Counting

2 min read

Anthropic API — Usage Reporting & Token Counting

Two distinct use cases: checking historical token/cost consumption for an API org, and counting tokens before sending a request.

Why / When to Use

  • Usage reporting: track spending, audit which models or workspaces consume most tokens, build cost dashboards.
  • Token counting: pre-flight check before sending a large prompt to avoid hitting context limits or unexpected costs.

Core Concept / Commands

1. Org Usage Report (API customers only)

Requires an Admin API key (sk-ant-admin...), not a regular API key. Create one in the Claude Console under Org Settings → API Keys.

import requests
from datetime import datetime, timedelta
 
ADMIN_KEY = "sk-ant-admin..."  # Admin API key — not a regular key
 
end = datetime.utcnow()
start = end - timedelta(days=7)
 
response = requests.get(
    "https://api.anthropic.com/v1/organizations/usage_report/messages",
    params={
        "starting_at": start.strftime("%Y-%m-%dT%H:%M:%SZ"),
        "ending_at":   end.strftime("%Y-%m-%dT%H:%M:%SZ"),
        "bucket_width": "1d",
        "group_by[]":  "model",
    },
    headers={
        "x-api-key": ADMIN_KEY,
        "anthropic-version": "2023-06-01",
    }
)
 
data = response.json()
for bucket in data.get("data", []):
    print(bucket)

Cost report endpoint (dollars):

GET /v1/organizations/cost_report

2. Token Counting (pre-send, free)

Uses the count_tokens method — same inputs as a normal message, returns input token count. No charge.

import anthropic
 
client = anthropic.Anthropic(api_key="sk-ant-...")
 
response = client.messages.count_tokens(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.input_tokens)

Key Options / Variants

EndpointAuth RequiredWhat It Returns
/v1/organizations/usage_report/messagesAdmin API keyToken counts by model/workspace/date
/v1/organizations/cost_reportAdmin API keyDollar costs
client.messages.count_tokens()Regular API keyInput token count for a given prompt

Gotchas

  • Claude.ai subscription plans (Free/Pro/Max) have no programmatic usage API. Limits and usage are only visible in the app UI.
  • Admin API keys are separate from regular API keys. Only org admins can create them.
  • count_tokens does not charge tokens or make an inference — it’s purely a counting call.
  • The group_by[] parameter supports: model, workspace, service_tier, api_key_id.

Source

Conversation: “Checking Claude API usage programmatically” — 2026-05-16

Graph View