@rawdash/connector-anthropic

Track Anthropic spend, daily token usage across Claude models, cache hit volumes, and web-search tool requests from the Anthropic Admin API.

Install

npm install @rawdash/connector-anthropic

Authentication

Authenticates with an Anthropic organization admin API key (sk-ant-admin-). Admin keys are the only key class that can read the Usage and Cost reports; regular API keys return 403.

1. Open console.anthropic.com -> Settings -> Admin Keys and create a new admin key. Admin keys are organization-scoped, so create the key from the organization whose usage you want to read.
2. Store the key as a secret (e.g. ANTHROPIC_ADMIN_API_KEY).
3. Reference it from config as adminApiKey: secret("ANTHROPIC_ADMIN_API_KEY").
4. Optionally set workspaceIds to restrict the query to a subset of workspaces.

Configuration

| Field | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | adminApiKey | secret | Yes | Anthropic organization admin API key (starts with sk-ant-admin-). Create one at console.anthropic.com -> Settings -> Admin keys. Regular API keys (sk-ant-api-) cannot read the Usage and Cost reports. | | workspaceIds | array | No | Restrict usage and cost queries to specific Anthropic workspace ids (wrkspc_...). Omit to aggregate every workspace the admin key can see. | | resources | array | No | Which Anthropic metric series to sync. Omit to sync all of them. The five usage metrics share one upstream call to the Messages Usage Report; enabling any one of them fetches the report and writes all five. | | lookbackDays | number | No | How many days of usage history to fetch on a full sync. Defaults to 30. The Usage Report returns at most 31 buckets per page, so longer windows paginate. |

Resources

• anthropic_input_tokens (metric) - Daily uncached input tokens processed by the Anthropic Messages API, grouped by model and workspace.
  • Endpoint: GET /v1/organizations/usage_report/messages
  • Unit: tokens
  • Granularity: daily
  • Dimensions: model, workspace_id, api_key_id, service_tier, context_window, inference_geo
  • Sample value is uncached_input_tokens. Cache-read and cache-creation token volumes are mirrored on their own metrics so a cache hit ratio can be computed at query time.
• anthropic_output_tokens (metric) - Daily output tokens generated by the Anthropic Messages API, grouped by model and workspace.
  • Endpoint: GET /v1/organizations/usage_report/messages
  • Unit: tokens
  • Granularity: daily
  • Dimensions: model, workspace_id, api_key_id, service_tier, context_window, inference_geo
  • Written alongside anthropic_input_tokens from the same usage_messages API call.
• anthropic_cache_read_tokens (metric) - Daily input tokens read from the prompt cache, grouped by model and workspace.
  • Endpoint: GET /v1/organizations/usage_report/messages
  • Unit: tokens
  • Granularity: daily
  • Dimensions: model, workspace_id, api_key_id, service_tier, context_window, inference_geo
  • Cache hits are charged at a fraction of the uncached rate, so this metric paired with anthropic_input_tokens gives the cache hit ratio.
• anthropic_cache_creation_tokens (metric) - Daily input tokens written into the prompt cache (sum of the 1h and 5m ephemeral caches), grouped by model and workspace.
  • Endpoint: GET /v1/organizations/usage_report/messages
  • Unit: tokens
  • Granularity: daily
  • Dimensions: model, workspace_id, api_key_id, service_tier, context_window, inference_geo
  • The per-cache-bucket counts (ephemeral_1h_input_tokens, ephemeral_5m_input_tokens) are mirrored in attributes for finer-grained widgets.
• anthropic_web_search_requests (metric) - Daily count of web-search tool requests executed server-side by Claude, grouped by model and workspace.
  • Endpoint: GET /v1/organizations/usage_report/messages
  • Unit: requests
  • Granularity: daily
  • Dimensions: model, workspace_id, api_key_id, service_tier, context_window, inference_geo
  • Sourced from server_tool_use.web_search_requests on each usage bucket. Zero rows are still written so a "no usage today" widget renders correctly.
• anthropic_cost_usd (metric) - Daily organization spend in USD, broken down by workspace and cost line item, pulled from the Anthropic Cost Report.
  • Endpoint: GET /v1/organizations/cost_report
  • Unit: USD
  • Granularity: daily
  • Dimensions: workspace_id, description, cost_type, model, token_type, service_tier, context_window, currency
  • The Cost Report returns amounts as a decimal string in the lowest currency unit (cents for USD). The connector divides by 100 so the stored metric value is dollars. Costs can be revised for a couple of days after the fact; incremental syncs refetch a short trailing window to pick up adjustments.

Example

import {
  defineConfig,
  defineDashboard,
  defineMetric,
  secret,
} from '@rawdash/core';

const anthropic = {
  name: 'anthropic',
  connectorId: 'anthropic',
  config: {
    adminApiKey: secret('ANTHROPIC_ADMIN_API_KEY'),
  },
};

export default defineConfig({
  connectors: [anthropic],
  dashboards: {
    ai: defineDashboard({
      widgets: {
        spend_mtd: {
          kind: 'stat',
          title: 'Anthropic spend (last 30d)',
          window: '30d',
          metric: defineMetric({
            connector: anthropic,
            shape: 'metric',
            name: 'anthropic_cost_usd',
            fn: 'sum',
          }),
        },
        input_tokens_today: {
          kind: 'stat',
          title: 'Input tokens today',
          window: '1d',
          metric: defineMetric({
            connector: anthropic,
            shape: 'metric',
            name: 'anthropic_input_tokens',
            fn: 'sum',
          }),
        },
      },
    }),
  },
});

Rate limits

The Admin API returns 429 with a Retry-After header on burst; the shared HTTP client honors it automatically. Daily syncs against the Usage and Cost reports are well below the per-organization Admin API budget.

Limitations

• Only the organization Messages Usage Report and Cost Report endpoints are synced. Per-request logs and individual message bodies are not exposed by the Admin API.
• All samples are bucketed daily (1d bucket_width). The Usage Report also supports hourly and per-minute granularity but those are not exposed here in v1.
• The Cost Report only supports 1d bucket_width and reports cost in USD; non-USD billing currencies are not converted.
• Admin API keys are required - regular sk-ant-api- keys do not have access to the organization Usage and Cost reports.

Links

• Rawdash docs
• Anthropic API docs
• GitHub

License

Apache-2.0