> 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/get-started/quickstart/5-minute-quickstart.md).

# Connect Your Coding Assistant & Code Repository

Connect an AI coding assistant and your code repository — GitHub or GitLab — to see how your team uses AI coding tools and what those tools deliver. In under 10 minutes you have the assistant connected and your usage dashboards live — per-tool and per-developer usage and cost against API-equivalent value. Per-developer productivity metrics that pair AI spend with the pull requests your developers ship appear once your code host is connected and its first sync completes.

You will connect the assistant first — that alone populates the usage dashboards — then connect your code repository to add the per-developer productivity view.

***

### <i class="fa-list-radio">:list-radio:</i> Before you begin

You need a Revenium account.

<a href="https://app.revenium.ai/" class="button primary">Sign in or Register</a>

***

## How it works

1. You connect a coding assistant, which sends usage telemetry to Revenium.
2. Revenium groups that usage by tool, team, and developer, and estimates its API-equivalent value.
3. You connect GitHub or GitLab, which adds shipped pull requests as an output signal.
4. Revenium cross-references spend against delivery and shows per-developer productivity metrics.

***

## 1. Get your metering key

In Revenium, open [**Connections → SDK Setup**](https://app.revenium.ai/connections/sdk-setup) and copy your metering key (it begins with `rev_mk_`). This key authenticates telemetry from your coding assistant into your Revenium account. Keep it handy for the next step.

## 2. Connect your coding assistant

Revenium connects Claude Code, Codex, Gemini CLI, GitHub Copilot, and Cursor. In **Connections**, each assistant has a ready-to-paste setup prompt — select your tool, copy the prompt, and paste it into that assistant. The prompt already contains your key and the exact commands, so this is the quickest path. Repeat for each assistant you want to track.

Four of the five are set up from the command line, using one package:

```bash
npm install -g @revenium/cli
```

Each assistant then has its own setup command:

| Assistant      | Setup command                                  |
| -------------- | ---------------------------------------------- |
| Claude Code    | `revenium-metering setup --api-key <your-key>` |
| Codex          | `revenium-codex setup --api-key <your-key>`    |
| Gemini CLI     | `revenium-gemini setup --api-key <your-key>`   |
| GitHub Copilot | `revenium-copilot setup --api-key <your-key>`  |

After setup, reload your environment so the assistant picks up the new configuration — the setup output tells you how (for example `source ~/.claude/revenium.env` for Claude Code, or `exec $SHELL` for Codex). Then confirm it worked:

```bash
revenium-metering status        # shows the resolved configuration
revenium-metering test --verbose # sends a test metric end to end
```

**Cursor is different — it needs no CLI install.** Cursor usage is synced by Revenium directly: in the dashboard open **Connections → Providers**, click **Link Provider**, select **Cursor**, and enter your Cursor **team** API key (a personal user key will not work). Revenium then syncs Cursor usage every 5 minutes.

**GitHub Copilot has prerequisites** before its setup command will work: Copilot Business or Enterprise on your organization, the **Copilot usage metrics** policy enabled in your GitHub org settings, and a GitHub classic token with `manage_billing:copilot`, `read:org`, and `admin:org`. Copilot data flows continuously once you start the sync (`revenium-copilot sync --watch`).

{% hint style="info" %}
**Rolling out to a whole team?** Coding assistants that support centrally-managed configuration can be set up once by an administrator and delivered to every developer automatically, with no per-developer install. See your assistant's centrally-managed configuration documentation for that; the per-user command above is for fast individual onboarding and for importing historical usage.
{% endhint %}

Run a short session in your assistant. Usage appears in Revenium after the next telemetry flush.

## 3. Connect your code repository for per-developer attribution

Your code host adds output data — merged pull requests, or merged requests on GitLab — so you can measure delivery next to spend. Revenium connects to **GitHub and GitLab**; the walkthrough below uses GitHub, and the GitLab flow is the same shape.

1. In Revenium, open **Connections → Integrations**, where GitHub, GitLab, and Slack are connected.
2. On the GitHub card, choose **Connect** and enter your GitHub organization.
3. Provide a read-only token. Revenium gives you a **Create a pre-filled token on GitHub** button that pre-selects exactly the permissions needed — Pull requests and Metadata (read-only) under Repository permissions, plus Members (read-only) under Organization permissions. If you only have a classic token, `repo` (or `public_repo` for public-only orgs) plus `read:org` also works, though it grants more than Revenium needs.
4. Choose the repositories to track, or connect the whole organization — pull requests are counted across every repo in the org.
5. Save the connection.

For GitLab, connect a personal access token with the `read_api` and `read_user` scopes; Revenium then counts merged merge requests per user across your group.

{% hint style="info" %}
**A fine-grained GitHub token may need org approval.** When the token targets an organization, an org owner or admin has to approve it before it can read org data. Until then the connection can show as **Connected** while pull request and member data stays empty — check **Settings → Third-party Access → Personal access tokens → Pending requests** in your GitHub org if nothing appears after a sync.
{% endhint %}

For per-developer attribution to line up, the email addresses on your developers' commits should match the email addresses Revenium has for those developers. Org members are auto-mapped by email, and you can edit the mapping for anyone who does not match automatically.

The first sync is not instant — give it a few minutes before you expect to see pull request data.

Revenium splits AI-assisted from human-authored work using the `Co-Authored-By` trailers at the bottom of commits. The default pattern is `noreply@anthropic.com`, which covers Claude Code. If your team uses other AI assistants that sign commits, add their signatures — one pattern per line — on the same card; work without a matching trailer simply counts as human-authored.

## 4. See your dashboards and productivity metrics

Open **Intelligence → AI Assistants** in the sidebar.

* The **Overview** shows every connected tool side by side — active users and total cost per tool for the period you select, plus aggregate adoption, sessions per user, usage trend, and API-equivalent value.
* Each tool has its own **per-tool dashboard** with a per-user breakdown: who is using it, how many sessions they run, how many tokens they consume, and what that costs.
* On the **Claude Code** tab, once your code host is connected, the **Value by User** table gains three productivity columns:

  | Column              | What it shows                                    |
  | ------------------- | ------------------------------------------------ |
  | **PRs Merged**      | Pull requests the developer merged in the period |
  | **PRs with Claude** | Pull requests where a commit was AI co-authored  |
  | **Cost/PR**         | AI spend divided by pull requests merged         |

  Connect GitLab instead and the same columns count merged merge requests, labelled **MRs** and **Cost/MR**.
* The **By Employee** tab rolls every connected assistant and direct API spend up to the individual — the view for chargebacks and for spotting concentrated spend. Start with the **Attribution Coverage** figure, which tells you how much of your identifiable AI spend is tied to a known person.

That is the full picture: usage, cost, and per-developer delivery, all in one place.

### Where to go next

* [Analyze AI tooling spend](/track-and-control-costs/analyze-ai-tooling-spend.md) — go deeper on who is using which assistant, how intensively, and whether the seats you bought are earning their cost.
* [Set budgets and alerts](/track-and-control-costs/set-budgets-and-alerts.md) — put caps on that spend and get told in Slack when a team or tool spikes.

***

## Instrument your own code or API traffic

The steps above connect off-the-shelf coding assistants. If instead you want to meter an application you build — your own AI calls or API traffic — Revenium acts as zero-latency middleware: install the SDK, set your keys, and wrap your client.

### Install the SDK

{% tabs %}
{% tab title="Python" %}

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

{% endtab %}

{% tab title="NodeJS" %}

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

{% endtab %}

{% tab title="Direct API" %}

```bash
curl -X POST "https://api.revenium.ai/meter/v2/ai/completions" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_REVENIUM_API_KEY" \
    -d '{
      "transactionId": "<your-per-request-uuid>",
      "provider": "openai",
      "model": "gpt-4o-mini",
      "operationType": "CHAT",
      "inputTokenCount": 200,
      "outputTokenCount": 500,
      "totalTokenCount": 700,
      "stopReason": "END",
      "requestTime": "2026-05-22T00:00:00Z",
      "completionStartTime": "2026-05-22T00:00:01Z",
      "responseTime": "2026-05-22T00:00:02Z",
      "requestDuration": 2000,
      "organizationName": "acme-corp",
      "productName": "saas-app-gold-tier",
      "agent": "support-agent",
      "traceId": "conv-28a7e9d4"
    }'
```

{% hint style="info" %}
**`transactionId` is your correlation key.** Generate a UUID in your application *before* the AI call and send it to Revenium. Re-use it on retries — Revenium dedupes by `transactionId` so retries won't double-count. Send only one of `transactionId` or `spanId` per request.
{% endhint %}

{% hint style="info" %}
**Pick the right host for your key.** Keys minted in production target `https://api.revenium.ai`. Keys minted in a dev/staging tenant target that environment's API host — the SDKs read this from `REVENIUM_METERING_BASE_URL` (overrideable per environment). If the curl above returns `403 Forbidden`, your key is for a different environment than the host it was sent to.
{% endhint %}
{% endtab %}
{% endtabs %}

### Set environment variables

```bash
# Your Revenium Routing & Auth
# Metering key (rev_mk_*): metering-only scope used by the SDK + OTLP to emit metering events to Revenium.
export REVENIUM_METERING_API_KEY="your_revenium_api_key"
# Provider key: your standard provider API key used for the actual LLM call (swap for ANTHROPIC_API_KEY, etc. when using other providers).
export OPENAI_API_KEY="your_openai_api_key"
```

### Wrap your client

{% tabs %}
{% tab title="Python" %}

```python
import openai
import revenium_middleware.openai

response = openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {
            "role": "user",
            "content": "What is the meaning of life, the universe and everything?",
        },
    ],
    max_tokens=500,
    usage_metadata={
         "trace_id": "conv-28a7e9d4",
         "task_type": "summarize-customer-issue",
         "subscriber": {
             "id": "subscriberid-1234567890",
             "email": "user@example.com",
             "credential": {
                 "name": "engineering-api-key",
                 "value": "actual-api-key-value"
             }
         },
         "organization_name": "acme-corp",
         "subscription_id": "startup-plan-Q1",
         "product_name": "saas-app-gold-tier",
         "agent": "support-agent",
         "ticket_id": "JIRA-123",  # or set REVENIUM_TICKET_ID in your environment
    },
)
print(response.choices[0].message.content)
```

{% endtab %}

{% tab title="NodeJS" %}

> Requires ESM — set `"type": "module"` in `package.json`, or wrap the call in an `async` function.

```typescript
import { Initialize, GetClient } from "@revenium/middleware/openai";

Initialize();
const openai = GetClient();

const response = await openai.chat().completions().create(
  {
    model: "gpt-4o-mini",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      {
        role: "user",
        content: "What is the meaning of life, the universe and everything?",
      },
    ],
    max_tokens: 500,
  },
  {
    traceId: "conv-28a7e9d4",
    taskType: "summarize-customer-issue",
    subscriber: {
      id: "subscriberid-1234567890",
      email: "user@example.com",
      credential: {
        name: "engineering-api-key",
        value: "actual-api-key-value",
      },
    },
    organizationName: "acme-corp",
    subscriptionId: "startup-plan-Q1",
    productName: "saas-app-gold-tier",
    agent: "support-agent",
    ticketId: "JIRA-123", // or set REVENIUM_TICKET_ID in your environment
  }
);

console.log(response.choices[0].message.content);
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**traceId is the field you plan around.** transactionId is auto-generated by the SDK (from the OpenAI response id) or by Revenium (if you omit it on a direct API call). What you control is `traceId` — use it to group multiple AI calls that belong to one user request, conversation, or workflow. Plan your `traceId` scheme — session, conversation, or job ID — before instrumenting, so related calls group consistently from the start.
{% endhint %}

For deeper attribution, budgets, and monetization, continue with [Attribute Your Usage](/track-and-control-costs/instrument-your-code.md), [Set Budgets & Alerts](/track-and-control-costs/set-budgets-and-alerts.md), and [Monetize Your Apps](/monetize-your-ai/tutorial-build-usage-based-billing.md).


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.revenium.io/get-started/quickstart/5-minute-quickstart.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.