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.

Deliveries are idempotent — re-fetching an overlapping window upserts instead of duplicating, so overlapping runs are safe by design.

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

Install

pip install revefi-usage-collection-sdk

Run it on AWS Lambda (hourly, trailing 3 hours)

The recommended deployment: a small Lambda function triggered by an EventBridge schedule every hour, each run collecting the last 3 hours of data. Windows are aligned to the top of the UTC hour, and the 3-hour window overlaps the 1-hour schedule 3×, so a transient failure or a missed invocation loses nothing — the next run re-covers it.

1. The handler

Save as lambda_function.py:

import os

from revefi_usage_sdk import AnthropicProvider, RevefiSink, UsageCollector


def lambda_handler(event, context):
    provider = AnthropicProvider(admin_key=os.environ["ANTHROPIC_ADMIN_KEY"])
    sink = RevefiSink(
        ingest_url=os.environ["REVEFI_INGEST_URL"],
        token=os.environ["REVEFI_TOKEN"],
    )
    try:
        collector = UsageCollector(provider)
        report = collector.run(sinks=[sink], hours=3, assume_yes=True)
    finally:
        sink.close()

    if not report.ok:
        # Raising marks the invocation failed so CloudWatch alarms fire.
        raise RuntimeError(f"collection failed: {report.errors}")
    return {
        "window": f"{report.window_start.isoformat()}..{report.window_end.isoformat()}",
        "cost_records": report.cost_records,
        "usage_records": report.usage_records,
    }

2. Package it

Lambda needs the SDK bundled alongside the handler:

mkdir package
pip install revefi-usage-collection-sdk --target package
cp lambda_function.py package/
(cd package && zip -qr ../revefi-usage-lambda.zip .)

3. Create the function

Console: Lambda → Create function → runtime Python 3.12, upload the zip, handler lambda_function.lambda_handler. Or via CLI:

aws lambda create-function \
  --function-name revefi-usage-collector \
  --runtime python3.12 \
  --handler lambda_function.lambda_handler \
  --zip-file fileb://revefi-usage-lambda.zip \
  --role arn:aws:iam::<ACCOUNT_ID>:role/<basic-lambda-execution-role> \
  --timeout 300 --memory-size 256

Then set the configuration:

• Environment variables: ANTHROPIC_ADMIN_KEY, REVEFI_TOKEN (store these in AWS Secrets Manager or as encrypted Lambda env vars), and REVEFI_INGEST_URL=https://gateway.revefi.com/api (the SDK appends /v1/ai-usage/anthropic, so deliveries go to https://gateway.revefi.com/api/v1/ai-usage/anthropic).
• Timeout: 300 s. Requests to Anthropic are paced ~1/s and rate-limit retries can wait up to 2 minutes — don't use the 3 s default.
• Memory: 256 MB is plenty.
• Networking: the function needs outbound internet (to api.anthropic.com and Revefi). The default no-VPC Lambda has it; if you attach the function to a VPC, it must have a NAT gateway route.
• IAM: only the basic execution role (CloudWatch logging) — the function calls no AWS APIs.

4. Schedule it hourly

aws scheduler create-schedule \
  --name revefi-usage-hourly \
  --schedule-expression "rate(1 hour)" \
  --flexible-time-window Mode=OFF \
  --target '{"Arn": "arn:aws:lambda:<REGION>:<ACCOUNT_ID>:function:revefi-usage-collector", "RoleArn": "arn:aws:iam::<ACCOUNT_ID>:role/<scheduler-invoke-role>"}'

(Or in the console: Amazon EventBridge → Scheduler → Create schedule, rate 1 hour, target the Lambda.)

5. Alert on failures

The handler raises on any failure, so the invocation errors. Add a CloudWatch alarm on the function's Errors metric:

aws cloudwatch put-metric-alarm \
  --alarm-name revefi-usage-collector-errors \
  --namespace AWS/Lambda --metric-name Errors \
  --dimensions Name=FunctionName,Value=revefi-usage-collector \
  --statistic Sum --period 3600 --evaluation-periods 3 --threshold 3 \
  --comparison-operator GreaterThanOrEqualToThreshold \
  --alarm-actions arn:aws:sns:<REGION>:<ACCOUNT_ID>:<your-alerts-topic>

Alert if it fails repeatedly — a silently dead collector is indistinguishable from zero spend. (Threshold 3-in-3-hours tolerates a transient blip that the overlapping window already covers.)

Keeping the SDK up to date

Lambda packages are immutable, so the deployed SDK version is pinned until you redeploy. Re-run step 2 and aws lambda update-function-code --function-name revefi-usage-collector --zip-file fileb://revefi-usage-lambda.zip when Revefi announces an update (or wire those two commands into your CI on a weekly schedule).

Known limitations (Anthropic API)

• Cost data is served per completed UTC day — the current day's spend is not queryable until the day closes; hourly runs deliver it on the first run after UTC midnight.
• ~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.