revefi-usage-collection-sdk

Collect your AI provider usage and cost data inside your own environment and deliver it to Revefi — nothing has to leave your side except what you choose.

Currently supported provider: Anthropic (Usage & Cost Admin API). The record model is provider-neutral; OpenAI and Amazon Bedrock are planned.

How it works

1. You create an Anthropic Admin API key (sk-ant-admin01-..., Console → Settings → Organization → Admin keys). The key never leaves your environment — this SDK calls Anthropic directly from wherever you run it.
2. The SDK fetches two datasets:
   • Cost — daily billed line items (/v1/organizations/cost_report): exact dollars by model, workspace, token type, cost type, context window, service tier.
   • Usage — token counts at minute grain (/v1/organizations/usage_report/messages): uncached/cached input, cache writes, output tokens, web-search requests, by workspace/API key/model/tier/context window.
3. The raw API response pages are sent to Revefi, verbatim, as gzipped NDJSON over HTTPS (one JSON line per response page, each carrying its request window/params alongside). Revefi normalises server-side, so nothing is dropped client-side.

Only aggregate usage/cost rows are collected — no prompts, completions, or message content.

Install

pip install revefi-usage-collection-sdk

Quick start (CLI)

export ANTHROPIC_ADMIN_KEY=sk-ant-admin01-...
export REVEFI_INGEST_URL=https://gateway.revefi.com/api/v1/usage/ingest
export REVEFI_TOKEN=...   # provided by Revefi

# See exactly what would be sent — writes local NDJSON only, sends nothing
revefi-usage export --days 7 --out ./audit --audit-only

# Check credentials/connectivity
revefi-usage test-connection --sink revefi

# Collect the trailing 2 days and send to Revefi
revefi-usage collect --sink revefi --days 2

Configuration precedence: CLI flags > environment variables > --config revefi-usage.yaml (scaffold one with revefi-usage init).

Scheduling

collect is one-shot and idempotent — deliveries upsert, so overlapping windows never duplicate data. Run it daily from cron with a 2-day trailing window: each run re-fetches yesterday and today, so a single missed run loses nothing.

To update the SDK and run the ingestion manually as a single command:

python3 -m pip install --quiet --upgrade revefi-usage-collection-sdk; revefi-usage collect --sink revefi --days 2 --yes

(; rather than && so a failed update check still runs the collection.)

For cron, save this as /opt/revefi/collect.sh — it updates the SDK from PyPI first (an update failure is logged but never blocks collection), then runs the ingestion:

#!/usr/bin/env bash
set -u
python3 -m pip install --quiet --upgrade revefi-usage-collection-sdk \
  || echo "$(date -u +%FT%TZ) WARN: SDK update failed; proceeding with installed version"
python3 -m revefi_usage_sdk.cli collect --sink revefi --days 2 --yes

# daily at 02:00, re-fetching the trailing 2 days (restated data upserts in place)
0 2 * * * . /etc/revefi-usage.env && /opt/revefi/collect.sh >> /var/log/revefi-usage.log 2>&1

collect exits non-zero on any failure — alert on that. A silently dead collector is indistinguishable from zero spend.

Quick start (SDK)

from revefi_usage_sdk import AnthropicProvider, UsageCollector, RevefiSink

provider = AnthropicProvider(admin_key="sk-ant-admin01-...")
collector = UsageCollector(provider)

# Just get typed records and do your own thing
cost, usage = collector.fetch(days=2, bucket_width="1m")

# Or deliver to Revefi (failures are aggregated in the report)
report = collector.run(sinks=[RevefiSink(ingest_url=..., token=...)], days=2)
assert report.ok, report.errors

Known limitations (Anthropic API)

• ~90 days of history at the source — backfill cannot go further.
• Priority Tier dollars are absent from the cost endpoint (the tokens do appear in usage with service_tier: priority).
• The admin endpoints do not exist for Claude on Amazon Bedrock / Google Vertex organisations, or for individual (non-organization) accounts.
• Data lands ~5 minutes after requests complete; keep polling to at most once per minute.