Install

pip install capsera

Requires Python 3.11 or later. The only runtime dependency is httpx. The SDK does not install any provider library, because it patches the ones you already have.

Add it to your project:

# requirements.txt
capsera>=0.3.0

# pyproject.toml
[project]
dependencies = ["capsera>=0.3.0"]

Create an API key

In Capsera, go to Settings, then API keys, and create one. Keys are prefixed cap- and shown only at creation. The dashboard stores a hash, so a lost key must be rotated rather than recovered.

Set the key in your environment

export CAPSERA_API_KEY="cap-..."

The SDK reads no configuration file. If CAPSERA_API_KEY is missing, init() is usually never called, and the SDK stays inactive. Nothing breaks and nothing is reported. An empty dashboard after a successful deploy is almost always this.

Set the variable everywhere your application runs:

• production (Railway, Fly, ECS, a Kubernetes secret)
• staging, if you want staging spend reported separately
• CI, if your test suite makes real provider calls
• developer machines, if you want local spend attributed

Use a separate key for each environment and pass a matching env label, so development traffic does not mix into production reporting:

capsera.init(
    api_key=os.environ["CAPSERA_API_KEY"],
    env=os.environ.get("APP_ENV", "development"),
)

Where to call init()

Call init() once at startup, before the calls you want recorded. It patches the provider classes rather than individual client objects, so import order does not matter. Clients constructed before init() are still recorded.

# app/main.py
import os

import capsera

if os.environ.get("CAPSERA_API_KEY"):
    capsera.init(api_key=os.environ["CAPSERA_API_KEY"])

The if guard is the pattern Capsera's auto-instrumentation writes into repositories. Without a key the SDK stays inactive, so the same code runs unchanged on a machine that has no Capsera credentials.

Calling init() twice is safe. The patch is applied once per class, so a second call cannot double-record calls. Re-initialising points the emitter at the new configuration.

Verify the install

import capsera
print(capsera.__version__)

After init() has run, check which providers were patched:

capsera.init(api_key="cap-...")
print(capsera.get_interception_report())

{'anthropic.messages': 'patched',
 'anthropic.messages_async': 'patched',
 'openai.chat_completions': 'patched',
 'openai.embeddings': 'patched',
 'google.genai': 'not-installed',
 'bedrock.converse': 'not-installed', ...}

patched means calls through that surface are recorded. not-installed means the library is absent, which is expected for providers you do not use. unpatched means the library is present but init() has not run.

Next, Quickstart makes a first attributed call. If you have already deployed and see no data, go to Verify it works.