# Analyze Decision Costs For agent workflows, the unit of cost that matters isn't the token or the call - it's the *decision*. A support agent that handles 1,000 tickets incurs 1,000 decision costs, each of which involved some combination of LLM calls, tool invocations, and occasionally human escalations. The token cost of a single LLM call tells you almost nothing about whether the agent is profitable. The cost of the whole decision - from triggering event to business outcome - is the number that answers whether the workflow is worth running. Revenium models this as a **Job**: a higher-level abstraction that sits above transactions and traces, identified by an `agenticJobId` you supply when metering. A single job groups everything that contributed to delivering one business outcome - potentially many LLM calls, many tool invocations, and any human time that got pulled in along the way. Once outcomes are reported against those jobs, you can see the economics at the level that actually matters: did this category of decision make money, lose money, or break even. This works the same regardless of how the agent is built. LangChain chains, CrewAI crews, custom orchestration - Revenium doesn't care which framework assembled the workflow, because you're the one assigning the `agenticJobId` when you meter. The framework decides how the agent runs; you decide what counts as "one decision" for economic purposes. The analysis surface lives under **Intelligence > Costs & Revenue > ROI Dashboard**. > **Term Reference** > > * **Execution Status** reflects technical workflow completion (`SUCCESS`, `FAILED`, `CANCELLED`). > * **Outcome Type** captures the business result (`CONVERTED`, `DEFLECTED`, `ESCALATED`, `UNSUCCESSFUL`, `CUSTOM`). > * **Outcome Value** is the monetary value the workflow generated or saved. ### :ruler: What the Dashboard Measures The ROI dashboard is built around one equation that the Value Composition card makes explicit: **Business Value = Revenue from Conversions + Costs Avoided from Deflections** Two things produce value. A **conversion** is when a job delivered a positive outcome that generated revenue - a closed sale, a completed sign-up, a successful resolution where the customer was charged. A **deflection** is when a job completed a unit of work that would otherwise have required a more expensive path - a support ticket handled without escalation to a human agent, an automated review that replaced manual work. Conversions and deflections are the two economic outcomes that justify an agent existing. Against that value, three kinds of cost are tracked, visible on the Cost Composition card: * **Token Costs** - the AI provider spend for LLM calls * **External Tools** - spend on registered tools that agents called during the job (see [Monitor Agent Tool Usage](/instrument-your-agents/monitor-agent-tool-usage.md)) * **Human Escalation** - time spent by human reviewers, metered as a custom tool (Engineering Time in the example workspace) These three categories combine into **Total Costs**. The Value Composition card shows four headline metrics together: **Total Costs**, **Business Value**, **Net Value** (Business Value minus Total Costs — positive means profitable, negative means over-spending), and the **Value Ratio** (Business Value ÷ Total Costs — how many dollars of value each dollar of cost produced). The Value Ratio is the figure the dashboard leads with, because it answers the question every AI product leader actually asks: *are these agents paying for themselves?* ### :filters: The Two Conversion Funnels The Overview has two funnels side by side, and the distinction between them is the key insight the page is built around. **Conversion Funnel** (the revenue side): Total Jobs → Successful → Converted. The first drop-off is technical - some jobs failed execution. The second drop-off is the interesting one - jobs that ran without technical errors but didn't deliver the business outcome they were trying to produce. The ratio of Successful → Converted is the **Conversion Rate**. **Cost Avoidance Funnel** (the deflection side): Total Jobs → Successful → Deflected. Same shape, different outcome. Successful jobs either converted, deflected, or did neither. The Deflection Rate measures how often technical success produced cost savings rather than revenue. A job that's technically successful but doesn't convert *and* doesn't deflect is one that ran cleanly and produced no economic value. These are usually the most interesting jobs to investigate, because they represent spend without return - the agent did its work competently and no business outcome came out the other end. The gap between "successful" and "converted or deflected" is where the optimization opportunity lives. ### :up: How Outcomes Get Reported Each job ends with an outcome being reported against it. The API supports five outcome types: * **CONVERTED** - the job delivered a positive business outcome that generated revenue (a closed sale, a completed signup, a charged resolution) * **DEFLECTED** - the job successfully completed work that would otherwise have required a more expensive path (a ticket handled without human escalation, an automated review that replaced manual effort) * **ESCALATED** - the job required human escalation to complete. The business value still gets reported at full value; the human cost gets metered separately * **UNSUCCESSFUL** - the job ran technically without error but did not achieve the business goal, and was not escalated * **CUSTOM** - any outcome type your organization defines that doesn't fit the four standard categories. Useful for domain-specific outcomes that don't map cleanly to convert/deflect/escalate - tiered qualification scores, partial completions, multi-stage deal progressions Jobs that haven't yet had an outcome reported display in the UI as **Pending** - this is a UI-side status indicator, not an outcome type you can post through the API. Outcomes carry both a value and a currency - USD by default, with support for EUR, CAD, GBP, JPY, and other major currencies. Useful when you operate internationally and want ROI calculations to respect the currency of each market rather than blending everything into a single base currency. **Outcomes are immutable.** Once a job's outcome is reported, it can't be changed - attempting to report again returns a 409 Conflict. This is deliberate: the business outcome of a job is historical fact, and allowing edits would undermine the integrity of every ROI calculation built on top. If a reported outcome turns out to be wrong, it's wrong in the record, and future jobs get the corrected reporting. Execution Status and Outcome Type are independent dimensions. Execution Status captures whether the technical work completed without error (SUCCESS, FAILED, or CANCELLED); Outcome Type captures what the job produced in business terms. A job can be SUCCESS with an outcome of CONVERTED, or SUCCESS with an outcome of UNSUCCESSFUL (ran cleanly, business goal missed), or any other combination. The reason these are separate is that technical execution and business outcome are different questions - and conflating them is how teams end up thinking an agent is "working" when it isn't actually delivering. ### :list: The All Jobs View The **All Jobs** tab under ROI gives you the drill-down - every job execution in the selected time window, filterable by Job Type, Status, Outcome, and Value Range, searchable by Job ID or name. Each row shows Job ID, Name, Type, Status, Outcome Type, Job Value, and when it was created. Clicking through to an individual job shows the complete execution history - every transaction that contributed to the job, every tool call, the full cost composition, and the job's final business value. This is the path you take when the aggregate numbers raise a question: why did this specific job cost what it did, and what did it actually produce? ### :list-timeline: Per-Job-Type Analysis The Overview includes a **Job Types by Value Ratio** table that ranks every job type in your system by how profitable it is. Value Ratio, Net Value, Total Cost, Cost per Outcome, Conversion count, Deflection count, Job count, and Success Rate all sit next to each other - so you can tell at a glance which job types deliver most economically, which deliver consistently but cost too much, and which run successfully but fail to produce outcomes. Job types with an N/A value ratio are usually ones where outcomes haven't been reported yet - the technical execution is happening but the business layer isn't closing the loop. Seeing these is itself useful: it tells you which job categories need outcome reporting wired up before their economics can be measured. The **Value vs Cost Analysis** chart underneath shows the same per-job-type breakdown visually - one bar per job type split between Business Value, Token Cost, External Tools, and Human Escalation, with Value Ratio overlaid as a star. The chart makes a specific pattern obvious: job types where cost is dominated by Human Escalation rather than tokens are usually candidates for investigation, because human time scales linearly with volume in a way that token and tool costs don't. ### :square-check: Handling Escalated Outcomes Correctly A common mistake when reporting outcomes is to discount the value of escalated jobs to account for human involvement. A support ticket worth $143 that got escalated to a human agent might be reported with half the value, on the theory that the human did half the work. This produces misleading ROI. The right approach keeps value and cost as independent dimensions: * **Keep the `outcomeValue` at full value** - the business result was still delivered, even if a human helped * **Meter the human effort as a tool cost** - register an "Engineering Time" tool in the Tool Registry and meter the duration of the human session (see [Monitor Agent Tool Usage](/instrument-your-agents/monitor-agent-tool-usage.md) for the pattern) * **Let the ROI formula do the work** - Total Cost increases with tool costs, value stays accurate, and ROI comes out right Discounting value hides where the cost went. Metering human time as a tool cost surfaces it where it belongs - in the cost side of the equation. The Value Ratio and ROI numbers reflect the real economics of the workflow, including the parts of it that humans performed. ### :timeline-arrow: Business Value Over Time The **Business Value Over Time** chart plots value generated by each job type across the date range. Spikes tell you which job types drove revenue or cost savings on specific days. Flat lines across multiple job types alongside a spike in one means that job type accounted for the day's value. Patterns in this chart often align with external events - deploys, campaign launches, support volume changes - and knowing which job type drove the change is usually more useful than knowing that total value went up. > **Through MCP, conversationally.** Tracking agent job ROI is one of the capabilities the MCP Server explicitly supports. Once an AI assistant is connected to Revenium, you can ask the kind of questions this dashboard exists to answer without opening it. "What's the ROI on our agents this week?", "which agent is generating the most business value right now?", or "are AI costs trending up faster than the value they're producing?" The agent runs the queries, breaks the data down across providers, models, customers, agents, or API keys, and tells you what's changed. Useful when the question is recurring, like a weekly ROI check, rather than a one-off investigation. ### :gear-code: Telemetry Fields for Job Tracking Include the agentic job fields on every completion payload that should roll up into a job. Any transactions sharing the same `agenticJobId` automatically group under that job — costs, tokens, and transaction counts aggregate in real time. ```json { "agenticJobId": "support-ticket-12345", "agenticJobType": "support-ticket", "agenticJobName": "Handle Support Ticket #12345", "agenticJobVersion": "1.0.0", "model": "gpt-5.5", "provider": "openai", "totalCost": 0.05 } ``` | Field | Required | Constraint | Purpose | | ------------------- | ----------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `agenticJobId` | Yes | string, max 256 chars | Unique identifier for this job execution. The grouping key for everything that contributes to one decision. | | `agenticJobType` | Recommended | string, max 128 chars (lowercased) | Job category — drives the Job Types by Value Ratio table. | | `agenticJobName` | Recommended | string, max 512 chars | Human-readable name shown in the dashboard. | | `agenticJobVersion` | Recommended | string, max 64 chars | Tracks job evolution; useful for A/B comparing prompt or workflow changes. | Revenium creates the job entity the first time it sees a new `agenticJobId`, so no separate "create job" call is required. *** ### :rectangle-api: Reporting Outcomes via API After a job completes, post the outcome to the Jobs endpoint: ```bash curl -X POST "https://api.revenium.ai/profitstream/v2/api/jobs/{jobId}/outcome?teamId={yourTeamId}" \ -H "x-api-key: $REVENIUM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "executionStatus": "SUCCESS", "outcomeType": "CONVERTED", "outcomeValue": 500.00, "metadata": "{\"customerId\": \"123\", \"notes\": \"Upgraded to premium\"}" }' ``` | Field | Required | Allowed Values | | ----------------- | -------- | --------------------------------------------------------------- | | `executionStatus` | Yes | `SUCCESS`, `FAILED`, `CANCELLED` | | `outcomeType` | Optional | `CONVERTED`, `ESCALATED`, `DEFLECTED`, `UNSUCCESSFUL`, `CUSTOM` | | `outcomeValue` | Optional | Monetary value (number) | | `metadata` | Optional | JSON string with additional context | **Response codes:** `200 OK` — outcome recorded; `409 Conflict` — outcome already reported (immutable, do not retry); `404 Not Found` — job ID unknown. Outcomes can also be reported from the UI: open a job from the All Jobs tab, click **Report Outcome**, fill in the form. *** ### :list-check: Use Cases #### Support Ticket Deflection Track cost savings when AI handles tickets that would otherwise hit a human agent. Typical economics: deflection rate 60–80%; AI cost per deflected ticket $0.05–0.15 vs $50 for a human; ROI in the tens of thousands of percent for deflected tickets. #### Sales Lead Qualification Measure conversion value and validate that AI qualification is paying for itself. Typical economics: conversion rate 10–30%; AI cost per lead $0.10–1.50; ROI driven entirely by revenue per converted lead vs total cost across all qualified leads. *** ### :clipboard-list-check: Best Practices for Job IDs and Naming **Use meaningful, entity-derived `agenticJobId` values.** The ID should map to a real-world thing your business cares about, not a synthetic UUID: Good job IDs usually include the business entity and workflow, such as a support ticket, order, pull request, or onboarding run. Avoid generic labels, random UUIDs with no business context, broad batch names that collapse many decisions into one job, and transaction-level IDs that make every metered call look like its own job. **Use lowercase, hyphen-separated `agenticJobType` names.** Be specific (`loan-application-review`, not `review`), action-oriented (`lead-qualification`, not `leads`), and consistent across the codebase. Examples: `customer-support-chat`, `code-review-security`, `content-blog-generation`, `fraud-detection-realtime`. **Always report outcomes — even for failed and escalated jobs.** Skipping outcome reporting on failures hides your true success rate, autonomy rate, and cost-per-successful-outcome. For failed jobs, post `executionStatus: FAILED` and omit `outcomeType` and `outcomeValue`. For escalated jobs, post `executionStatus: SUCCESS`, `outcomeType: ESCALATED`, and the **full** business value — the human cost gets metered separately as a tool cost (see [Handling Escalated Outcomes Correctly](#handling-escalated-outcomes-correctly) above). **Be consistent in how you value outcomes.** Unit-economics analysis only works if the value side is methodologically clean. | Job Type | Value Strategy | | ------------------ | --------------------------------------------------------------------------------------------------------------------------- | | Support tickets | Average human agent cost per ticket for deflected; full business value for escalated (with human time metered as tool cost) | | Sales leads | Actual contract value for conversions, or average deal size as proxy | | Code reviews | Developer time saved at $100–200/hour | | Content generation | Attributed revenue from campaigns, or freelancer cost savings | Use conservative estimates, document your methodology, keep it consistent across similar job types, and revisit the numbers periodically as actual data lands. *** ### :code: Via API For current endpoint details, request and response schemas, and authentication requirements, use the [API reference](https://revenium.readme.io). *** ### See also * [SDK code examples](https://github.com/revenium/revenium-python-sdk) * [API reference](https://revenium.readme.io) --- # 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/instrument-your-agents/analyze-decision-costs.md?ask= ``` 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.