> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/integrations/sdk-setup.md).

# SDK Setup

Use SDK Setup when you are instrumenting an application directly with Revenium SDKs, middleware, API keys, and integration identifiers. Start here if you are adding metering to code you own.

## What You Need

* A Revenium API key with the right scope for your integration.
* Your tenant, team, and environment identifiers.
* The API base URL for your workspace.
* A choice of integration path: SDK, middleware, OTLP, MCP, Revvy CLI, or direct API.

## Recommended Next Steps

1. Review [API Key Permissions](/integrations/api-key-permissions.md) before creating production keys.
2. Choose an implementation path from [Integration Options](/integrations/integrations.md).
3. Use [Provider Integrations](/integrations/provider-integrations.md) for billing-provider account connections.
4. Use [OTLP Integration](/integrations/otlp-integration.md) if your stack already emits OpenTelemetry.

## <i class="fa-python">:python:</i> Python SDK

Install only the providers you need:

| Provider                           | Install command                                        |
| ---------------------------------- | ------------------------------------------------------ |
| OpenAI or Azure OpenAI             | `pip install "revenium-python-sdk[openai]"`            |
| Anthropic or Anthropic via Bedrock | `pip install "revenium-python-sdk[anthropic]"`         |
| Google Gemini                      | `pip install "revenium-python-sdk[google-genai]"`      |
| Google Vertex AI                   | `pip install "revenium-python-sdk[google-vertex]"`     |
| LiteLLM                            | `pip install "revenium-python-sdk[litellm]"`           |
| LiteLLM Proxy                      | `pip install "revenium-python-sdk[litellm-proxy]"`     |
| Ollama                             | `pip install "revenium-python-sdk[ollama]"`            |
| Perplexity                         | `pip install "revenium-python-sdk[perplexity-openai]"` |
| Fal.ai                             | `pip install "revenium-python-sdk[fal]"`               |
| LangChain                          | `pip install "revenium-python-sdk[langchain]"`         |

You can install multiple extras together, for example:

```bash
pip install "revenium-python-sdk[openai,anthropic,langchain]"
```

### AWS Bedrock permissions

The SDK calls Bedrock with your own AWS credentials, so those credentials need these IAM permissions. The two lookup permissions apply from SDK version 0.10.0.

| Permission                              | When you need it                                                                                                                                                         |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bedrock:InvokeModel`                   | Always.                                                                                                                                                                  |
| `bedrock:InvokeModelWithResponseStream` | Always.                                                                                                                                                                  |
| `bedrock:GetInferenceProfile`           | When you call Claude by an application inference profile ARN, through raw boto3 with `REVENIUM_BEDROCK_TRANSPORT=1` or through `AnthropicBedrock` with cost controls on. |
| `bedrock:GetProvisionedModelThroughput` | When you call Claude through a Provisioned Throughput ARN with `REVENIUM_BEDROCK_TRANSPORT=1`.                                                                           |

With `REVENIUM_BEDROCK_TRANSPORT=1`, raw `boto3.client("bedrock-runtime")` calls to Claude (`invoke_model`, `invoke_model_with_response_stream`, `converse`, `converse_stream`) are metered and capped. An application inference profile ARN (`arn:aws:bedrock:<region>:<account>:application-inference-profile/<id>`) and a Provisioned Throughput ARN (`arn:aws:bedrock:<region>:<account>:provisioned-model/<id>`) do not name the model, so the SDK looks each ARN up to learn which Claude model it runs. The lookup runs once per process, in the background, starting at the ARN's first call. It never delays your call, so calls made before it answers, usually only the first, are neither metered nor capped. After that, the SDK records and caps the call under that Claude model (for example `anthropic.claude-haiku-4-5-20251001-v1:0`).

A Provisioned Throughput call is recorded at the on-demand equivalent cost of its tokens, not the hourly price AWS bills. A cost cap fills at that rate, so a breached cost cap can stop calls on capacity you have already paid for.

With cost controls on, a sync `AnthropicBedrock` call by an application inference profile ARN is also capped under the Claude model the profile routes to. It uses the same lookup and the same `bedrock:GetInferenceProfile` permission.

{% hint style="warning" %}
Without the lookup permission, raw boto3 calls through these ARNs still go through, but they are unmetered and uncapped, and the SDK logs one warning per ARN. An `AnthropicBedrock` call by a profile is still metered, but a cap on its model cannot stop it. Profiles and Provisioned Throughputs that run a non-Claude model are not metered.
{% endhint %}

If Bedrock returns `AccessDenied`, check that your credentials have `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`. Add `bedrock:GetInferenceProfile` if you use application inference profile ARNs, and `bedrock:GetProvisionedModelThroughput` if you use Provisioned Throughput ARNs.

**Package:** [`revenium-python-sdk`](https://pypi.org/project/revenium-python-sdk/) on PyPI · **Source & examples:** [github.com/revenium/revenium-python-sdk](https://github.com/revenium/revenium-python-sdk) ([examples](https://github.com/revenium/revenium-python-sdk/tree/main/examples))

## <i class="fa-node">:node:</i> Node.js Middleware

Use the unified middleware package and provider sub-paths:

| Provider              | Package                              |
| --------------------- | ------------------------------------ |
| OpenAI / Azure OpenAI | `@revenium/middleware/openai`        |
| Anthropic             | `@revenium/middleware/anthropic`     |
| Google Vertex AI      | `@revenium/middleware/google/vertex` |
| Google AI SDK         | `@revenium/middleware/google/genai`  |
| Perplexity            | `@revenium/middleware/perplexity`    |
| LiteLLM               | `@revenium/middleware/litellm`       |

Install from npm:

```bash
npm install @revenium/middleware
```

### Version 2.0.0 and later

Version 2.0.0 of [`@revenium/middleware`](https://www.npmjs.com/package/@revenium/middleware) adds:

* **Filtered cost controls.** A [cost control](/track-and-control-costs/cost-controls.md) that filters on a provider, model, agent, product or another dimension stops only the calls it covers, and calls outside its filters go through. The middleware checks cost controls before OpenAI and Azure OpenAI chat completions. If your code builds an `EnforcementRule` object, add its `filters` list, typed by the exported `EnforcementFilter`.
* **Tool calls in a job.** `meterTool` and `reportToolCall` attach the job a tool call runs in, so the job's cost includes its tool calls. Both accept an optional `costUsd`, which Revenium charges in place of the price configured for that tool.
* **Environment files.** The middleware reads `.env.local` and `.env` from the folder your application starts in. A value in `.env.local` wins over one in `.env`, and a variable already set in the environment wins over both. A `.env` in a parent folder is not read, so start the application in the folder that holds the file, or set the variables in the environment.

**Package:** [`@revenium/middleware`](https://www.npmjs.com/package/@revenium/middleware) on npm · **Source & examples:** [github.com/revenium/revenium-node-sdk](https://github.com/revenium/revenium-node-sdk) ([examples](https://github.com/revenium/revenium-node-sdk/tree/main/examples))

## <i class="fa-golang">:golang:</i> Go SDK

Install:

```bash
go get github.com/revenium/revenium-go-sdk/openai
```

**Source & examples:** [github.com/revenium/revenium-go-sdk](https://github.com/revenium/revenium-go-sdk) ([examples](https://github.com/revenium/revenium-go-sdk/tree/main/examples)) · **Docs:** [pkg.go.dev](https://pkg.go.dev/github.com/revenium/revenium-go-sdk/openai)

Install the provider module you need — `openai` here. Each provider ships as its own module.

Minimal OpenAI setup:

```go
import (
    "os"

    "github.com/revenium/revenium-go-sdk/openai"
)

err := openai.Initialize(
    openai.WithOpenAIAPIKey(os.Getenv("OPENAI_API_KEY")),
    openai.WithReveniumAPIKey(os.Getenv("REVENIUM_METERING_API_KEY")),
)
if err != nil {
    return err
}

client, err := openai.GetClient()
```

## Frameworks and Agent Tooling

| Framework or tool                                          | Start here                                                                                                                                                                                                                                     |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LangChain                                                  | Use the Python `langchain` extra, or use [OTLP Integration](/integrations/otlp-integration.md) if your app already emits OpenTelemetry.                                                                                                        |
| n8n                                                        | Use the Revenium n8n middleware packages for OpenAI ([n8n-nodes-revenium](https://www.npmjs.com/package/n8n-nodes-revenium)) or Anthropic ([n8n-nodes-revenium-anthropic](https://www.npmjs.com/package/n8n-nodes-revenium-anthropic)) agents. |
| OpenInference / OpenLLMetry                                | Use [OTLP Integration](/integrations/otlp-integration.md).                                                                                                                                                                                     |
| Claude Code, Gemini CLI, Cursor, and other AI coding tools | Use [Context7 and AI Docs Access](/integrations/context7.md), [MCP Server](/integrations/mcp-server.md), or [Revvy CLI](/integrations/revvy-cli.md) depending on the workflow.                                                                 |
| JetBrains IDEs (IntelliJ, PyCharm, GoLand, etc.)           | Use [Revvy CLI](/integrations/revvy-cli.md) for guided instrumentation — scans your codebase, finds AI call sites, and walks through SDK setup.                                                                                                |

## Usage Metadata

SDKs accept optional usage metadata for billing, attribution, and alerting. The fields accepted on `POST /meter/v2/ai/completions` are:

| Field                  | Purpose                                                                                                                                                                                                           |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organizationName`     | Top-level customer account. Required — the legacy `organizationId` alias is silently dropped.                                                                                                                     |
| `productName`          | Commercial tier or SKU. Required — the legacy `productId` alias is silently dropped.                                                                                                                              |
| `subscriber`           | Object: `{ id, email, credential: { name, value } }` — the end customer plus their specific API key.                                                                                                              |
| `agent`                | Agent name making the call; powers per-agent cost views and the Tool Registry.                                                                                                                                    |
| `traceId`              | Links sequential AI calls into a single execution path for Trace Analytics.                                                                                                                                       |
| `taskType`             | Categorises the work the agent was doing (qualification, support, code review, etc.).                                                                                                                             |
| `subscriptionId`       | The Revenium subscription this call rates against.                                                                                                                                                                |
| `responseQualityScore` | `0.0–1.0` evaluation score from RAGAS, LLM-as-judge, human review, or other quality signals.                                                                                                                      |
| `ticketId`             | Optional engineering ticket or work-item identifier. Spend that carries it shows on Tickets; see [Tie Agent Work to a Ticket](/instrument-your-agents/agent-instrumentation-guide.md#tie-agent-work-to-a-ticket). |

{% hint style="info" %}
Revenium stores `subscriber.credential.value` to match usage to a credential and masks it to its last four characters when read back. To avoid sending a live key, send a stable key ID or a hash of the key instead, as [Manage Customers & Credentials](/monetize-your-ai/manage-customers-and-credentials.md) explains.
{% endhint %}

At minimum, pass `organizationName` + `productName`. Add `subscriber.id` to attribute usage and cost to individual end users, and `agent` and `traceId` to unlock agent-level cost views and Trace Analytics. The remaining fields are optional.

For OpenTelemetry attribution, see the `revenium.*` attributes in [OTLP Integration](/integrations/otlp-integration.md#deep-attribution-with-revenium-attributes).

## Related

* [API Reference](https://revenium.readme.io)
* [Revvy CLI](/integrations/revvy-cli.md)
* [Context7 and AI docs access](/integrations/context7.md)
* Python SDK — [PyPI](https://pypi.org/project/revenium-python-sdk/) · [GitHub](https://github.com/revenium/revenium-python-sdk)
* Node middleware — [npm](https://www.npmjs.com/package/@revenium/middleware) · [GitHub](https://github.com/revenium/revenium-node-sdk)
* Go SDK — [pkg.go.dev](https://pkg.go.dev/github.com/revenium/revenium-go-sdk/openai) · [GitHub](https://github.com/revenium/revenium-go-sdk)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.revenium.io/integrations/sdk-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.