Agent ROI attribution

Agent ROI answers one question per AI agent: is this agent returning more than it costs? It puts the agent’s model-call cost (what the agent spent on LLM tokens in a window) against the attributed revenue of the outcomes it resolved (what the resolved conversations were worth to you), and reports the difference as a margin. If two agents both sound good in demos, this is the surface that tells you which one is actually paying for itself. The dashboard at Insights → Agent ROI in the Orbit console renders these numbers per agent, with an org-wide daily trend and a config form for the pricing assumptions. The same data is available over the API — for endpoint shapes and every field, see the Insights API reference. This guide explains what the numbers mean and how to set the assumptions responsibly.

What ROI measures

For a selected window, every metric is computed per agent and summed for the org:

AI cost — the model-call spend recorded for the agent’s conversations in the window (the same ledger that feeds the LLM spend dashboard).
Attributed revenue — the count of resolved outcomes the agent passed, priced by your value-per-outcome config (below). A conversation counts when it reaches a resolved status or passes an outcome rubric.
Margin — attributed revenue minus AI cost, plus a margin_percent (margin over revenue). A positive margin means the agent returned more than it spent; negative means it cost more than its outcomes were priced at.

Attributed revenue is not billed revenue. It is your own assumption applied to resolved outcomes — the dashboard labels it that way (“Revenue is attributed from resolved outcomes using the assumptions above — it is not billed revenue”). The config you set is an estimate of what one resolved outcome is worth to your org, so ROI is only as meaningful as the estimate you give it.

The three surfaces

The feature is one dashboard backed by three API endpoints:

Surface	Endpoint	What it gives you
Summary	`GET /api/v1/insights/agent-roi`	Per-agent cost, attributed revenue, margin, and outcome lines, plus org totals. The dashboard’s stat cards and “By agent” table read this.
Daily trend	`GET /api/v1/insights/agent-roi/timeseries`	One bucket per day with the same cost / revenue / margin numbers — the “Cost vs revenue” chart. Pass `agentId` to scope the trend to one agent.
Attribution config	`GET` / `PUT /api/v1/insights/agent-roi/config`	The value-per-outcome assumptions (below). The dashboard’s config card edits these; the summary response also echoes the current config so you can render “priced as of…”.

All reads are served from a read-replica with the org’s billing timezone applied to day boundaries — a day in the trend is your local day, not UTC.

Tuning attribution

Attribution is priced by a two-level lookup: an explicit per-rubric override if one exists, otherwise the org default, otherwise zero.

Field	Type	Notes
`default_outcome_value_cents`	integer \| `null`	Whole cents per passed outcome when no per-rubric override exists. `null` means “outcomes with no override count as $0”.
`per_rubric_value_cents`	object	Per-rubric overrides in cents, keyed by rubric id (up to 500 entries). An override takes priority over the default for that rubric.

PUT /api/v1/insights/agent-roi/config is a read-merge-write: both fields are optional, omitted fields keep their current value, and the server re-validates on write. Send null (not omitted) to clear the default.

# 1. Read the current config.
curl https://api.orbit.devotel.io/api/v1/insights/agent-roi/config \
  -H "X-API-Key: $ORBIT_API_KEY"

# 2. Set a $25 default per resolved outcome, and price one specific rubric
#    (a "booking completed" outcome) at $120. Any field you omit is left alone.
curl -X PUT https://api.orbit.devotel.io/api/v1/insights/agent-roi/config \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_outcome_value_cents": 2500,
    "per_rubric_value_cents": { "rub_8f3k2m9p1q": 12000 }
  }'

The dashboard’s config card lists every rubric seen in the selected window plus any rubric you have already priced, so you can fill in values without looking up rubric ids by hand.

Reading the dashboard

Open Insights → Agent ROI in the console. The layout, top to bottom:

Stat cards — org totals for the window: AI cost, attributed revenue, margin, and margin share, computed by summing every agent row.
Cost vs revenue trend — the daily org-wide trend. Margin is the gap between the cost and revenue lines on any given day.
Attribution config — the assumptions card (default + per-rubric values).
By agent table — one row per agent in the window: cost, attributed revenue, margin, margin %, outcome count, and the priced outcome lines (each rubric that contributed revenue, with its passed count and subtotal). Rows are ordered so the largest contributors are first; if your org has more agents than the page limit, a note under the table tells you the table is truncated.

A worked example. Your support agent’s summary row for the last 30 days reads:

AI cost: $412.00
61 resolved outcomes priced at $25.00 each:$ 1,525.00 attributed revenue
Margin: $1,113.00 (73% margin)

To track just that agent’s day-by-day picture:

curl "https://api.orbit.devotel.io/api/v1/insights/agent-roi/timeseries?agentId=agent_2k9xd4" \
  -H "X-API-Key: $ORBIT_API_KEY"

Read the trend with the assumptions in mind: because revenue is priced per outcome, a jump in attributed revenue means more outcomes resolved (or more expensive rubrics passing), not more traffic — the same conversation count with better resolution moves the revenue line while cost stays put. If the page shows “No AI agents configured yet”, the org has no agents at all — create one from the agents surface first. If agents exist but the cards read zero, the window has no agent traffic; widen the date range.

Role access

The Agent ROI dashboard and its API endpoints are visible to the owner, admin, developer, and billing roles only — the same guard as the LLM spend dashboard, since both surface aggregate cost and revenue numbers. Agent and viewer roles do not see the page in the console, and API calls from those roles are rejected.

API Reference

All Endpoints

Configure and read Agent ROI attribution

Agent ROI attribution

What ROI measures

The three surfaces

Tuning attribution

Reading the dashboard

Role access

See also

​Agent ROI attribution

​What ROI measures

​The three surfaces

​Tuning attribution

​Reading the dashboard

​Role access

​See also

Agent ROI attribution

What ROI measures

The three surfaces

Tuning attribution

Reading the dashboard

Role access

See also