API reference

Every public symbol in the capsera package: functions, decorators, types, and gateway entry points, with signatures, defaults, and failure behaviour.

The complete public surface of the capsera package. This reference covers SDK version 0.4.1 and describes behaviour as shipped, including where a call fails open and where it raises.

Anything newer than the oldest supported release is marked inline — "added in 0.4.0" and so on. Compare against capsera.__version__ rather than assuming the newest release is the one your environment resolved.

Pages in this section are for lookup. For the reasoning behind each mechanism, the sections above are the better read — Attribution model, init() options, and Reliability in particular.

The import surface

Everything below is available on the top-level package, apart from the three gateway entry points under capsera.gateways.

import capsera

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

capsera.__all__ is the authoritative export list. capsera.__version__ gives the installed version, which is the first thing to include in a bug report.

Functions

Symbol	Purpose
`init()`	Configure the SDK and install the provider patches. Call once at startup.
`flush()`	Ship queued events immediately.
`shutdown()`	Flush and stop the background thread.
`get_interception_report()`	Which provider and gateway surfaces are hooked right now.
`record()`	Record a usage event from a client the SDK does not patch.
`set_session()`	Set an ambient session ID for the current thread or task.
`clear_session()`	Remove the ambient session ID.

Decorators and scopes

Symbol	Purpose
`agent()`	Attribute every LLM call inside a function to an agent.
`tag()`	Attribute every LLM call inside a `with` block.
`framework_unit()`	Attribute a framework node, step, or task.
`langgraph_node()`	`framework_unit()` for a LangGraph node.
`crewai_agent()`	`framework_unit()` for a CrewAI agent entrypoint.
`crewai_task()`	`framework_unit()` for a CrewAI task.
`LangChainCapseraCallback`	LangChain callback handler that scopes attribution.

Types

Symbol	Purpose
`Config`	The resolved configuration `init()` produces.
`TokenEvent`	One captured LLM call, as sent to the backend.
`AgentContext`	Attribution metadata for one scope.
`BudgetExceededError`	Raised when a blocking budget stops a call.

Gateway entry points

Symbol	Purpose
`gateways.install_litellm()`	Register the LiteLLM SDK integration. Automatic in `init()`.
`gateways.install_portkey()`	Patch the Portkey SDK surfaces. Automatic in `init()`.
`gateways.litellm_proxy.capsera_handler`	Callback for a LiteLLM Proxy `config.yaml`.

What is not public

Modules whose name begins with an underscore — _interceptor, _emitter, _router, _pricing, _context, _models, _config, _catalog, _prompt_analyzer — are internal, and their contents change without notice. PromptMetadata and RoutingDecision are internal despite sitting alongside TokenEvent.

If you import from them anyway, one detail will bite you: capsera._interceptor as a package attribute is shadowed by an instance, not the module. Reach the module through importlib.import_module("capsera._interceptor").

The SDK is one half of the API surface. The REST API the backend exposes is documented separately by its OpenAPI schema at api.capsera.ai/docs.