> 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/optimize-performance/ai-insights.md). # AI Insights AI-detected anomalies, cost opportunities, and operational issues — with suggested actions for each finding. AI Insights is a dedicated analytics surface that runs your AI usage data through Revenium's Recommendations Engine and surfaces the findings most worth acting on. Instead of reading dashboards and trying to spot what matters, Revenium analyzes your transaction history including costs, errors, and agent behavior, and hands you a prioritized list of recommendations with concrete suggested actions and the spend at stake. Each recommendation is grounded in your actual data (no hypothetical advice), tagged with severity and category, linked to the specific transactions that triggered it, and ranked by potential monthly savings. To see which agent, customer, person, or group a finding names, and how small findings are kept off the list, see [What a Finding Covers](/optimize-performance/ai-insights/what-a-finding-covers.md). ## Why this matters AI usage data accumulates faster than most teams have time to read. Patterns that meaningfully affect spend or reliability — wasted spend, agents failing silently, model costs growing faster than the usage that drives them — are scattered across transactions that nobody scans end-to-end. AI Insights surfaces those patterns automatically. Detectors run across every dimension of your usage and produce a prioritized list of findings, each grounded in your actual data with a potential monthly savings estimate, the affected transactions, and a concrete suggested action. ## How AI Insights works The Recommendations Engine runs a multi-stage pipeline looking across dozens of dimensions for optimization opportunities. The in-depth analysis takes a few minutes to complete. Open **Notification settings** to choose which configured webhook channels receive each Insights event: **Run completed**, **Run partial**, **Run failed**, and **Feedback recorded**. These analyzes can also be triggered and retrieved via API. ## Reading the Insights page ### Summary cards Four metric cards across the top of the page give you the headline view of the current run: * **Potential Monthly Savings** — The sum of estimated monthly savings across Waste and Efficiency recommendations, if each one is acted on. Concentration, Worth a Look and Reliability amounts are spend under review rather than savings, so they are not counted here. These are estimates derived from your actual usage data, not guarantees. * **Critical / High Severity** — Critical means immediate action is warranted with strong evidence of significant impact. High means a material problem that should be prioritized as soon as possible. * **Top Category** — The recommendation category contributing the largest share of impact in this run (Waste, Spend Concentration, Reliability, or Efficiency). Minor issues are also consolidated under a "Worth a Look" category for lower priority issues. * **Affected Spend** — The total AI spend linked to specific findings in the analyzed window. Potential Monthly Savings is the corresponding 30-day projection of recoverable spend; for 30-day analyzes it will be smaller than Affected Spend, while shorter windows (1d, 7d) may project monthly savings higher than the raw affected spend in that window. ### Recommendation cards Each recommendation appears as a card with: * **Severity badge** — Critical, High, Medium, Low, or Info. * **Category badge** — Waste, Worth a look, Concentration, Reliability, or Efficiency. * **Monthly impact** — A green badge showing the estimated monthly savings if non-zero. * **Detector label** — The specific pattern that triggered the recommendation (e.g. "Error concentration", "Outdated model"). * **Title and body** — A plain-English explanation of what was detected. Long bodies truncate with a **Read more** link. * **Affects**: the agents, models, credentials, subscribers, or other entities the finding applies to. * **Suggested action** — An expandable section with the specific change to make (swap model, adjust prompt, enable a setting, restructure the flow, etc.). * **Feedback controls** — Thumbs up / thumbs down, plus a dismiss button with reason picker. Switch between **By recommendation impact** (single ranked list across all categories) and **By category total** (grouped by category) using the toggle at the top of the list. Impact is totalled at three levels. Each card shows its own monthly impact. In **By category total**, each category heading shows the total for that category, and categories are ordered by that total. **Potential Monthly Savings** adds up the Waste and Efficiency categories only, and counts amounts in US dollars. ### Sample transactions and trace linking Expand any recommendation to see the sample transactions that triggered the finding — up to 20 transaction IDs per finding. For each sample you can: * **Copy** the transaction ID to clipboard. * **Open Trace** — Resolves the transaction to its enclosing trace and navigates to [Trace Analytics](/optimize-performance/debug-logs-and-traces.md) so you can inspect the full request path, latency breakdown, and downstream calls. * **Copy Transaction IDs** — Copies all transaction IDs if you wish to investigate these IDs in another system. ### Run history and time range The meta bar above the cards lets you: * **Switch runs** — Jump between past analyzes via the run history dropdown. * **Choose a time range** — Scope the analysis window to the past 1 day, 7 days, or 30 days (default). * **Run a new analysis** — Click **Analyze** to kick off a fresh run on the selected time range. Revenium starts analyzing automatically once your account has usage on three separate days, or sooner when it sends many calls. Each automatic analysis starts when you open the app and the latest run is out of date. Click **Analyze** whenever you want fresh findings sooner, for example after you change a model or a prompt. Each run states which spend it analyzed. When a run finds nothing to recommend, it also says whether coding-assistant spend was left out of the analysis and what share of the period's total that spend was. ## Recommendation categories Recommendations are grouped into five categories, each describing a different *kind* of problem. ### Waste > Spend you can eliminate without changing what the workload does — enable a setting, upgrade to current-generation pricing, or stop redundant work. Success rate and capability stay the same. Prompt cache miss and Dormant spend are two of the findings that usually land here. See [Named findings](#named-findings) for what each one flags and what to do about it. ### Concentration > A single subscriber, credential, agent, or model accounts for a disproportionate share of spend, errors, or exposure — creating fragility and limiting your optimization leverage. Acting on Concentration findings often unlocks downstream improvements — when one entity is responsible for a large share of issues, addressing it has outsized leverage even when the immediate dollar impact looks modest. ### Reliability > The workload is failing, retrying, or degrading at a rate that is itself the problem. Fix improves success rate; cost usually drops as a side effect. Reliability findings cover error concentration, throttling patterns, correlated error+retry, quality drops, and similar. ### Efficiency > The cost per successful completion is high relative to what the task warrants. Swap a model, rewrite a prompt, or restructure a flow to produce the same result for less. Efficiency findings flag places where the same outcome can be achieved for less spend. ### Worth a look > Something notable you probably haven't seen yet — either a cost that appeared or grew faster than usage justifies, or an option you didn't know was available (like a same-price newer model). These don't necessarily require action — they're surfaced because they're worth a glance. ## Named findings Each recommendation card carries a detector label that names the finding. The findings below cover wasted spend, answers cut off at the output limit, spend with no outcome or no customer attached, and spend spikes. Each entry says what the finding flags and what you do next. A finding's category can differ from its name: Retry waste, for example, usually appears under Reliability. ### Retry waste Flags calls that your application retried after an error, where the retries point to a recurring fault and not a one-off failure. The finding names the error, the agent and the model, counts the retried calls, and prices them as a monthly cost. **What to do:** fix the error behind the retries, or add backoff so a failing call is not retried again and again. The sample transactions on the card show which calls were retried. ### Truncation cluster Flags an agent whose responses often stop at the output token limit, so you pay for answers that end mid-thought. The finding names the agent and the model, counts the calls that hit the limit, and estimates their monthly cost impact. **What to do:** raise the output limit for that agent, or shorten what it is asked to produce. The sample transactions on the card show which calls were cut off. ### Prompt cache miss Flags three caching problems, each priced as the monthly saving from fixing it: * **Caching never used.** A model supports prompt caching and the workload has never used it. Turn caching on for that workload. * **Caching switched on but rarely reused.** The workload writes to the cache and seldom reads from it, which usually means content that changes on every call sits in the middle of the prompt. Move that content to the end, so the fixed opening of the prompt can be reused. * **Cache reuse has dropped.** The cache hit rate for a model is lower than in the previous period. Check what changed in the prompt or in how often the workload calls, and bring the hit rate back. **What to do:** follow the step for the case the card names: turn caching on, move the changing content to the end of the prompt, or find what lowered the hit rate. ### Model-task fit Points at spend on a model that is a poor fit for the work an agent gives it. The card names the agent, the task type, the model in use and the model to move to. **What to do:** move that task type to the named model, then check the result in a later run. ### Dormant spend Points at spend on an agent whose work is not tied to a business result. The card names the agent and shows what it costs per month. **What to do:** report outcomes for the jobs the agent runs, so its spend can be weighed against its value, or confirm that the workflow should still be running. See [AI Outcomes](/instrument-your-agents/agent-outcomes.md). The same label can also name a customer whose usage has stopped. Check whether the account has left, or whether its integration has stopped sending data. ### Attribution gap Flags spend that arrives with no customer attached, and shows what share of the period's spend that is. It fires when more than half of the period's spend outside coding assistants has no customer attached and that spend would come to at least $50 a month. **What to do:** [send the customer's organization with each call](/track-and-control-costs/instrument-your-code.md#enrich-calls-with-business-attribution). The spend can then be charged back and analyzed per customer. ### Spend trajectory Flags a spend spike: an agent, a subscriber (the person or service account behind the calls), a trace type or a job type whose daily spend has broken from its own history. Each one is compared with its own past spend, so you do not need to [set a budget](/track-and-control-costs/set-budgets-and-alerts.md) or a threshold first. The finding shows how far spend is above the norm for that agent, person or workload. It also says whether the cause is more activity or a higher cost per call. When cost per call has risen, it names the model that accounts for most of that spend. A spike on a credential, the API key a subscriber calls with, appears under the **Subscriber concentration** label. The card names the key. Check which application holds the key and whether the jump is expected. **What to do:** open the sample transactions to see what changed, then decide whether the new level of spend is expected. If it is not, the cause named on the card is the place to start. ## Types of issues AI Insights looks for Findings span these broad areas: * **Configuration waste**: workloads paying for outdated models, missed prompt caching, mismatched service tiers, or other settings that can be changed without affecting capability. * **Failure-driven cost**: errors, retries, throttling, and reliability issues that are themselves driving spend. * **Concentration risk**: a single subscriber, agent, credential, or model accounting for a disproportionate share of cost, errors, or exposure. * **Cost-to-outcome misalignment**: workloads where the cost per successful result is high relative to the value of the result. * **Better alternatives available**: newer or less expensive model options, or tasks better served by a different approach. * **Unexpected growth**: cost or call volume growing faster than the underlying usage that drives it. * **Cost outpacing usage**: spend that is climbing faster than the activity driving it, so cost per call is rising even when volume isn't. * **Out-of-pattern spenders**: a single agent, subscriber, credential, trace type, or job type that has broken from its own established spending pattern. * **Attribution gaps**: spend that can't be tied back to a known customer. * **Context waste**: agents, tasks, and repeating jobs that pull far more context into each call than the work needs, either as a standing pattern or as a jump since the previous period. Model upgrade recommendations also cover supported coding-assistant traffic that is [billed at API rates](/track-and-control-costs/analyze-ai-tooling-spend/configure-coding-assistant-billing-models.md). Their savings estimates price fresh input, output, cached input, and cache writes, so an upgrade can surface even when the meaningful price difference is in cached input. The recommendation tracks follow the current Anthropic, OpenAI, and Gemini model families and name both the model in use and the recommended replacement. When a model's cost per token rises, the finding names the price increase on that model. Context findings are produced from token counts alone. Revenium compares how much context a workload reads against how much output it produces, and estimates what the excess is costing, without reading your prompts or the model's responses. Because cached context is billed at a lower rate than fresh context, the estimate weighs the cost of the extra context rather than its raw size, so a workload that re-reads a warm cache is not treated as wasteful. Where the underlying cause is a caching problem rather than an oversized context, Insights reports it as the caching finding instead, so one problem produces one recommendation. ## Use cases * **Pre-renewal review** — Before a contract renewal or budget cycle, run a 30-day analysis to surface every Waste and Concentration finding for review. * **Incident triage** — When an alert fires for a cost or error spike, an Insights run scoped to the last day or seven days will frequently identify the root finding (error concentration, retry waste, throttling) without manual log diving. * **Quarterly review** — Compare runs across the quarter to track whether your findings are decreasing — i.e. whether the team is actually closing the optimization gaps. * **New integration validation** — After connecting a new model, agent, or middleware, run Insights a week later to catch any unexpected fan-out, error patterns, or attribution gaps before they grow into problems. ## API integration To automate analysis runs or feedback, use the [API reference](https://revenium.readme.io) for current endpoints and schemas. To receive run and feedback events, see [AI Insights Webhooks](/integrations/ai-insights-webhooks.md). ## Frequently asked questions **Do I get charged for analysis runs?** Analysis runs are included in your Revenium subscription at no additional cost. **How often should I run an analysis?** You rarely need to. Once your account has enough usage data, Revenium starts one for you when you open the app and the latest run is out of date. Run one yourself after a change you want to check, such as a new model, prompt, or integration. **What if I don't have enough data yet?** Analysis starts on its own once your account has usage on three separate days, or sooner when it sends many calls. Some findings appear only once a longer history exists: a spend spike, for example, is measured against an agent's or a person's own past spend. **How are monthly savings estimated?** Savings are projected from the affected-spend slice over the analyzed window, scaled to a 30-day estimate, and adjusted by an estimated capture rate per detector. They're estimates, not guarantees. --- # 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/optimize-performance/ai-insights.md?ask=&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.