# FAQ

This FAQ is organized around what you're trying to do — not internal feature categories. Pick the scenario closest to yours: you're trying to get your AI agent reporting into Revenium, you want to see the full AI spend picture from your providers, you want guardrails before the invoice arrives, or you're troubleshooting why the numbers don't match what you expected. Each section answers the questions that come up in that context. For reference docs on specific features, follow the links.

***

### <i class="fa-rocket-launch">:rocket-launch:</i> Where do I start?

#### **I'm trying to instrument an AI agent versus using AI to interact with the platform — which path is this?**

Two distinct paths:

**Path A — Instrumenting your agent (most common):** You're sending data *to* Revenium. Your agent calls the Revenium SDK, OTLP endpoint, or direct API, and that data flows into your dashboards, cost controls, and AI Outcomes tracking. Most setup work lives here.

**Path B — Using Revenium's AI features:** You're using AI-powered features *within* Revenium — the MCP Server, AI Insights recommendations, or natural-language alert configuration. These features read your existing data and surface intelligence on top of it.

If you're just getting started, you're on Path A. See the [5-Minute Quickstart](/get-started/quickstart/5-minute-quickstart.md).

***

#### **What's the minimum I need to do to get any data into Revenium?**

Start with instrumentation — that's the per-call layer that unlocks the rest. Use the SDK or OTLP to send data for every AI call: which agent, which workflow, which subscriber. That's also what powers cost guardrails, per-customer attribution, and the AI Outcomes layer. See [API Key Permissions](/integrations/api-key-permissions.md) for key setup.

Provider integrations complement instrumentation — connect your AI providers in [Provider Integrations](/integrations/provider-integrations.md) to pull total spend per provider as a baseline. On their own, admin-key syncs are read-only and after-the-fact, so they're useful for visibility but not for control.

If you use AI coding tools — Claude Code, Cursor, Gemini CLI, or Codex — you can bring that spend in too. See [Analyze AI Tooling Spend](/track-and-control-costs/analyze-ai-tooling-spend.md).

Not sure where to begin? Try one of the [runnable examples](/get-started/quickstart/examples.md) — each one is self-contained and produces real data in your dashboard you can explore straight away.

The goal in all cases is [360 visibility](/track-and-control-costs/analyze-ai-tooling-spend.md): every AI dollar from every source, in one place.

***

#### **Which languages and frameworks are supported?**

See [Integration Options](/integrations/integrations.md) for the current list — that page is the single maintained reference for supported languages, frameworks, and connection paths.

***

### <i class="fa-360-degrees">:360-degrees:</i> Getting 360 visibility

#### **I want 360 visibility into my AI spend — what do I actually have to do?**

Two things, both required for the full picture:

1. **Connect your AI provider admin keys** in **Settings → Provider Integrations** — this pulls your provider billing data directly and shows you the total spend from each provider.
2. **Instrument your agents** with the SDK or OTLP — this gives you per-call attribution, subscriber-level breakdown, workflow-level ROI, and the control surface for guardrails.

Provider admin keys alone show you the total bill. Instrumentation shows you *why* — which agent, which workflow, which subscriber. Both together give you 360 visibility. The more data you send through instrumentation, the sharper the attribution picture gets.

***

#### **Do I need to send data, or will Revenium just see it through my provider admin keys?**

**Yes — you need to send data via the SDK or API.** Provider admin keys only cover one aspect of the picture: total billing data from each provider, read-only, after the spend has occurred. For cost controls to work, per-subscriber attribution, guardrails, and the AI Outcomes layer to function, your agents must send instrumented data into Revenium.

The control surface sits with your application — pre-call guardrails fire from the SDK before a request reaches the provider, which is only possible when your code is instrumented. Admin keys are a complementary baseline, not a substitute. Use the SDK for the easiest path to full coverage.

***

#### **I've connected my OpenAI / Anthropic admin key. Why aren't my cost controls firing?**

Provider admin key connections are billing-data syncs — they're read-only and happen after the fact. Cost controls require SDK instrumentation. When a guardrail rule is active, the SDK checks the rule *before* sending the call to the AI provider. If you're only using provider admin keys, Revenium sees the spend after it's already been incurred and can alert you, but cannot block the call.

See [Set Budgets & Alerts](/track-and-control-costs/set-budgets-and-alerts.md) for how to enable runtime enforcement.

***

#### **What attribution fields should I pass with each call?**

The more attribution you send, the richer the views available in Revenium — by customer, product, agent, task, workflow, and more. Every additional field unlocks a new slice in the dashboards and makes cost controls more precise. On top of per-call attribution sits the outcomes layer — see [AI Outcomes](/instrument-your-agents/agent-outcomes.md) — where each job closes with a business result (CONVERTED, DEFLECTED, ESCALATED, CUSTOM) so the ROI loop completes.

At minimum, pass these fields so events map cleanly to your configured resources:

* `organizationName` — top-level customer account (used when a single customer has multiple users or API keys). Accepts `organizationId` as an alias.
* `subscriber` — sub-object `{ id, email, credential: { name, value } }` identifying the end customer and their API key.
* `productName` — commercial tier or SKU. Accepts `productId` as an alias.
* `agent` — the agent making the call. Populates per-agent cost attribution and the Tool Registry.
* `taskType` — categorizes what the agent was doing (qualification, support, code review, etc.); shows up in per-task analytics.
* `traceId` — links sequential AI calls into a single execution path for Trace Analytics.

For the full field list including `subscriptionId` (the Revenium subscription this call rates against — distinct from the end-customer `subscriber.id`) and `responseQualityScore`, see [SDK Setup → Usage Metadata](/integrations/sdk-setup.md#usage-metadata). If you're emitting OpenTelemetry instead of using the SDK, see [OTLP Integration](/integrations/otlp-integration.md) for the `revenium.*` attribute equivalents.

***

#### **Will adding the Revenium SDK slow down my application?**

For normal telemetry, no. SDK metering calls run on a background thread after the model call returns — fire-and-forget. They do not block your application and add no measurable latency to your AI calls.

The one exception is when a cost guardrail rule is active. In that case, the SDK performs a synchronous check *before* sending the call to the AI provider. That check is what makes pre-execution budget enforcement possible — it has to happen before the call, so it runs in-line. If no guardrail rules are configured, every SDK call is fully asynchronous.

***

### <i class="fa-box-dollar">:box-dollar:</i> Cost control

#### **How do I set hard spending limits on AI usage?**

Budget rules in Revenium can operate in two modes: **NOTIFY** (alert when a threshold is crossed) and **ENFORCE** (block calls once the ceiling is reached). Both are configured in **Notifications → Alerts**.

For enforcement to work — meaning the SDK blocks the call before any spend is incurred — you need two things:

* **SDK instrumentation** on the agent making the calls. The SDK runs a synchronous pre-call check against the active rules. Without the SDK, Revenium can alert you after spend occurs but cannot block it.
* **Runtime enforcement enabled** on the rule. A rule set to NOTIFY only alerts — it does not stop execution. Switch it to ENFORCE to make it a hard gate.

If your stack emits OpenTelemetry instead, see [OTLP Integration](/integrations/otlp-integration.md) — you can implement your own pre-call check using the enforcement API, but the SDK handles this automatically.

The SDK's enforcement check happens at the call site, before the model sees the request. When a rule is breached, the call is blocked and `ReveniumCostLimitExceeded` is raised — no spend is incurred. See [Set Budgets & Alerts](/track-and-control-costs/set-budgets-and-alerts.md).

***

### <i class="fa-calculator-simple">:calculator-simple:</i> How does Revenium calculate my AI spend?

#### **How does Revenium calculate AI spend per request?**

When you use the SDK, Revenium automatically extracts model name, vendor, and token counts from the API response, then applies the current published pricing for that model. You don't calculate cost — Revenium does. Provider admin key data and SDK-metered data are reconciled together so the full spend picture reflects both sources.

If you're on a custom or negotiated pricing arrangement, set custom rates in **Settings → AI Models & Pricing** — that takes precedence over published pricing.

***

#### **Can I override the cost Revenium calculates?**

Yes, two paths depending on your setup:

* **Settings → AI Models & Pricing** (preferred for negotiated rates): set custom pricing for any model. This works whether you're using the SDK or the direct API and overrides published pricing for every cost calculation going forward.
* **Inline `totalCost` field** (direct API only): pass `totalCost` directly in your metering payload and Revenium will use your value instead of calculating it.

If your provider has given you negotiated pricing that differs from published rates, the Settings path is the right choice — it ensures all historical and future calculations use your rates. See [SDK Setup](/integrations/sdk-setup.md) and [OTLP Integration](/integrations/otlp-integration.md) for the relevant field references.

***

### <i class="fa-brain-arrow-curved-right">:brain-arrow-curved-right:</i> Understanding what Revenium finds

#### **How does AI Insights find waste and optimization opportunities in my usage?**

AI Insights runs Revenium's Recommendations Engine across your full transaction history — AI spend, errors, agent behavior, and model usage patterns — and produces a prioritized list of findings. Each finding is grounded in your actual data, tagged with severity and estimated monthly impact, and linked to the specific transactions that triggered it. Common findings include wasted spend on failed calls, over-sized models for simple tasks, and agents looping unexpectedly. The more instrumented data you send, the more precise the recommendations get. See [AI Insights](/optimize-performance/ai-insights.md) for the full reference.

***

#### **What happens when an agent fails its business outcome?**

Revenium's AI Outcomes layer classifies every agent execution as CONVERTED, ESCALATED, DEFLECTED, or CUSTOM — linking the technical result to a business result. When an agent fails to achieve its intended outcome, that execution is recorded against its outcome type so you can track failure rates, AI spend per outcome, and ROI at the workflow level. This separates technical success (did the call complete?) from business success (did it achieve what it was supposed to?). See [Agent Outcomes](/instrument-your-agents/agent-outcomes.md) for setup and the full taxonomy.

***

### <i class="fa-user-lock">:user-lock:</i> Privacy and data

#### **Does Revenium have access to prompt or response content?**

{% hint style="success" %}
**By default, no.** Revenium does not access, store, or analyze the raw input (prompts) or output (responses) of your AI calls unless you explicitly opt in.
{% endhint %}

Our SDK and APIs are designed to capture **usage metadata only** by default, such as:

* Token counts (input and output)
* Model type and latency
* Subscriber, organization, product, and agent attribution fields
* Optional quality or classification metrics

This enables precise AI spend tracking, performance alerts, and usage-based billing — **without exposing any user-generated content**.

Prompt capture is opt-in and controlled at multiple levels. A team admin must first enable it per team. Once enabled at the team level, individual users must be granted view access before they can see prompt content. Admins can restrict prompt viewing per user, or restrict it to a dedicated data context that only specific users can access. The default at every level is off — prompt data only flows when each layer has been explicitly configured.

#### **Where is data stored and processed?**

Data is processed and stored in US-based cloud infrastructure by default. EU region is available on Enterprise plans.

***

### <i class="fa-toolbox">:toolbox:</i> Troubleshooting

#### **Why does my first test event show missing or zero cost?**

This usually means Revenium accepted the event but did not receive enough cost-relevant metadata to price it.

**Common causes:**

* Using `imageCount` instead of `actualImageCount`
* Using `audioLength` instead of `audioDurationSeconds`
* Using `stop_reason` instead of `stopReason`
* Omitting the required `stopReason` field entirely

**How to fix:**

1. Review the API documentation to verify exact field names
2. Check the AI Analytics dashboard to confirm costs are being calculated
3. Use one of our [SDKs](/integrations/sdk-setup.md) to avoid field-name issues entirely — SDKs handle correct field mapping automatically

***

#### **How can I test whether usage is being tracked?**

Go to the AI Transactions log page in the Revenium UI to see usage, tokens, latency, and AI spend per call. You can also verify metadata like organizations, products, subscribers, and agents there. See [Debug Logs & Traces](/optimize-performance/debug-logs-and-traces.md) for guidance.

***

#### **What happens if I send metadata Revenium doesn't recognize?**

Because the SDK's metering call is async and non-blocking, your call to the AI provider continues unaffected — only the usage tracking to Revenium is skipped. Most SDKs log a warning via standard logging so you can identify and fix the issue. The AI provider call itself is never blocked by a metadata problem.

***

Still have questions? Visit [app.revenium.ai](https://app.revenium.ai) and use the in-app chat to reach the team.


---

# Agent Instructions: 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:

```
GET https://docs.revenium.io/faq/faq.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.