Insights API

Operator-facing analytics for your AI agents: how much they cost to run (LLM spend), the revenue they attribute and the margin they return (ROI), how often they resolve a conversation without a human (containment), and how each agent ranks against the rest of your org (comparison & benchmarks). These are read dashboards. They’re served from a database read-replica, so they’re cheap to call but lag the primary by 1-3 seconds. The PUT endpoints (budget, ROI config, and cost-economics rates) write to the primary and are read-back consistent. Base path: /api/v1/insights Authentication: API key (X-API-Key) or session JWT. Every request is scoped to the caller’s organization; you only ever see your own tenant’s data.

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.insights.getLlmSpend();

Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Conventions

These apply to every endpoint below.

Money is always integer cents. Fields ending in _cents are whole cents in the org’s wallet currency (returned as currency, e.g. USD). The API never converts to dollars or applies FX — format on the client.
Time ranges use from and to as ISO 8601 timestamps with an offset (e.g. 2026-06-01T00:00:00Z). from must be earlier than to, and the window may not exceed 365 days. Omit both to default to the last 30 days ending now; pass only one and the other is backfilled to a 30-day window.
Timezone-aware buckets. Day/month boundaries are computed in the org’s billing timezone (returned as timezone), not UTC, so a cap or trend lines up with your local day.
Envelope. Responses are wrapped as { "data": { … }, "meta": { "request_id": "…", "timestamp": "…" } }. The shapes below show the data payload.
Invalid query parameters return 422 with a details.issues array naming the offending field and a message.

LLM spend

Track how much your AI agents are spending on model calls, where it’s going, and whether you’re on track against a budget.

Method	Path	Purpose
`GET`	`/api/v1/insights/llm-spend/overview`	Header stat cards: today, month-to-date, projection, cap usage
`GET`	`/api/v1/insights/llm-spend/summary`	Spend grouped by agent, model, or conversation
`GET`	`/api/v1/insights/llm-spend/timeseries`	Spend over time (hourly or daily buckets)
`GET`	`/api/v1/insights/llm-spend/top-conversations`	The most expensive conversations in a window
`GET`	`/api/v1/insights/llm-spend/by-feature`	Spend broken down by AI feature/channel + threshold breaches
`GET`	`/api/v1/insights/llm-spend/budget`	Current AI budget config
`PUT`	`/api/v1/insights/llm-spend/budget`	Update the AI budget config

Overview

GET /api/v1/insights/llm-spend/overview takes no parameters. It’s the baseline header-stat call: today’s spend, month-to-date spend with a month-end projection and a vs-previous-period delta, the trailing 7-day spend, and how much of the configured daily cap is used. Three fields intentionally turn null instead of zero — read them as “not computable here”, not “zero”:

today.cap_percentage — null when no daily_cap_cents is set in the budget config. Set a cap (see Budget) before you wire an alert on it, or the comparison is meaningless.
month_to_date.projected_month_end_cents — null when there’s no historic spend pace to project from (typically on day 1 of a brand-new org’s first month).
month_to_date.vs_last_period_percent — null when the previous comparable period had no recorded spend to compare against.

curl https://api.orbit.devotel.io/api/v1/insights/llm-spend/overview \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/overview",
    headers={"X-API-Key": ORBIT_API_KEY},
)
print(r.json()["data"])

{
  "currency": "USD",
  "timezone": "America/New_York",
  "daily_cap_cents": 50000,
  "today": {
    "spend_cents": 12340,
    "cap_percentage": 24.7
  },
  "month_to_date": {
    "spend_cents": 184200,
    "projected_month_end_cents": 421000,
    "vs_last_period_percent": 12.4,
    "days_remaining_in_month": 13
  },
  "last_7d_spend_cents": 78900
}

Summary

GET /api/v1/insights/llm-spend/summary groups spend over a window.

Param	Type	Default	Notes
`from`	ISO 8601	last 30 days	Window start
`to`	ISO 8601	now	Window end
`groupBy`	`agent` \| `model` \| `conversation`	`agent`	How to group the spend
`limit`	integer	`50`	Max group rows (1-200)

The response always carries totals for the whole window plus a groups array ordered by cost descending. Row shape depends on groupBy: Group by agent — the default. Which agent is driving spend.

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/summary?groupBy=agent&from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/summary",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"groupBy": "agent", "from": "2026-07-01T00:00:00Z", "to": "2026-08-01T00:00:00Z"},
)
print(r.json()["data"]["groups"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "currency": "USD",
  "timezone": "America/New_York",
  "totals": {
    "total_tokens": 4120000,
    "total_cost_cents": 81200,
    "conversation_count": 4180
  },
  "groups": [
    {
      "group_id": "ag_sales_assist",
      "group_label": "Sales assist",
      "model": "acme/reasoning-large",
      "total_tokens": 1900000,
      "total_cost_cents": 42300,
      "conversation_count": 1870
    },
    {
      "group_id": "ag_support_front",
      "group_label": "Support front line",
      "model": "acme/reasoning-small",
      "total_tokens": 2220000,
      "total_cost_cents": 38900,
      "conversation_count": 2310
    }
  ]
}

Group by model — which model tier is the cost driver; useful before you swap providers or negotiate routing.

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/summary?groupBy=model" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/summary",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"groupBy": "model"},
)
print(r.json()["data"]["groups"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "currency": "USD",
  "timezone": "America/New_York",
  "totals": {
    "total_tokens": 4120000,
    "total_cost_cents": 81200,
    "conversation_count": 4180
  },
  "groups": [
    {
      "group_id": "acme/reasoning-small",
      "group_label": "acme/reasoning-small",
      "model": "acme/reasoning-small",
      "total_tokens": 2220000,
      "total_cost_cents": 38900,
      "conversation_count": 2470
    },
    {
      "group_id": "acme/reasoning-large",
      "group_label": "acme/reasoning-large",
      "model": "acme/reasoning-large",
      "total_tokens": 1900000,
      "total_cost_cents": 42300,
      "conversation_count": 1710
    }
  ]
}

Group by conversation — the single most expensive threads; same leaderboard as top-conversations but over an explicit window.

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/summary?groupBy=conversation&limit=5" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/summary",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"groupBy": "conversation", "limit": 5},
)
print(r.json()["data"]["groups"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "currency": "USD",
  "timezone": "America/New_York",
  "totals": {
    "total_tokens": 4120000,
    "total_cost_cents": 81200,
    "conversation_count": 4180
  },
  "groups": [
    {
      "group_id": "conv_9xQm4krT2h",
      "group_label": "conv_9xQm4krT2h",
      "model": "acme/reasoning-large",
      "total_tokens": 18450,
      "total_cost_cents": 612,
      "conversation_count": 1
    }
  ]
}

Timeseries

GET /api/v1/insights/llm-spend/timeseries buckets spend over time.

Param	Type	Default	Notes
`from`	ISO 8601	last 30 days (day) / 7 days (hour)	Window start
`to`	ISO 8601	now	Window end
`granularity`	`hour` \| `day`	`day`	Bucket size

Returns a series array of { bucket, total_tokens, total_cost_cents } ordered ascending. Hour granularity is capped at a 14-day window — use granularity=day for longer ranges, or you’ll get a 422. Daily buckets — the default dashboard trend.

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/timeseries?granularity=day" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/timeseries",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"granularity": "day"},
)
for point in r.json()["data"]["series"]:
    print(point["bucket"], point["total_cost_cents"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "granularity": "day",
  "timezone": "America/New_York",
  "series": [
    { "bucket": "2026-07-01", "total_tokens": 122000, "total_cost_cents": 2410 },
    { "bucket": "2026-07-02", "total_tokens": 138400, "total_cost_cents": 2760 },
    { "bucket": "2026-07-03", "total_tokens": 121100, "total_cost_cents": 2392 }
  ]
}

Hourly buckets — spot an intra-day spike (a runaway agent loop, a launch). bucket carries the full hourly timestamp instead of a date.

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/timeseries?granularity=hour&from=2026-07-03T00:00:00Z&to=2026-07-04T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/timeseries",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={
        "granularity": "hour",
        "from": "2026-07-03T00:00:00Z",
        "to": "2026-07-04T00:00:00Z",
    },
)
for point in r.json()["data"]["series"]:
    print(point["bucket"], point["total_cost_cents"])

{
  "from": "2026-07-03T00:00:00.000Z",
  "to": "2026-07-04T00:00:00.000Z",
  "granularity": "hour",
  "timezone": "America/New_York",
  "series": [
    { "bucket": "2026-07-03T09:00:00.000Z", "total_tokens": 4810, "total_cost_cents": 96 },
    { "bucket": "2026-07-03T10:00:00.000Z", "total_tokens": 5220, "total_cost_cents": 104 },
    { "bucket": "2026-07-03T11:00:00.000Z", "total_tokens": 31210, "total_cost_cents": 614 }
  ]
}

Top conversations

GET /api/v1/insights/llm-spend/top-conversations returns the most expensive threads in a window, for drill-down.

Param	Type	Default	Notes
`from`	ISO 8601	last 30 days	Window start
`to`	ISO 8601	now	Window end
`limit`	integer	`50`	Max rows (1-50)

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/top-conversations?limit=10" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/top-conversations",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"limit": 10},
)
for conv in r.json()["data"]["conversations"]:
    print(conv["conversation_id"], conv["total_cost_cents"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "currency": "USD",
  "timezone": "America/New_York",
  "conversations": [
    {
      "conversation_id": "conv_9xQm4krT2h",
      "agent_id": "ag_sales_assist",
      "agent_name": "Sales assist",
      "model": "acme/reasoning-large",
      "total_tokens": 18450,
      "total_cost_cents": 612,
      "started_at": "2026-07-30T14:22:11.000Z"
    },
    {
      "conversation_id": "conv_2fRt8wLaZb",
      "agent_id": "ag_support_front",
      "agent_name": "Support front line",
      "model": "acme/reasoning-small",
      "total_tokens": 35900,
      "total_cost_cents": 402,
      "started_at": "2026-07-29T09:05:42.000Z"
    }
  ]
}

By feature

GET /api/v1/insights/llm-spend/by-feature accepts from and to. It aggregates spend by AI feature/channel (e.g. voice, sms, inbox, kb; events with no channel attributed appear as unknown) so you can see which feature is driving cost. It also returns the current budget config and any threshold_breaches — channels that have crossed their configured per-channel cap.

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-feature?from=2026-05-19T00:00:00Z&to=2026-06-18T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-feature",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"from": "2026-05-19T00:00:00Z", "to": "2026-06-18T00:00:00Z"},
)
for f in r.json()["data"]["features"]:
    print(f["channel"], f["total_cost_cents"])

{
  "from": "2026-05-19T00:00:00.000Z",
  "to": "2026-06-18T00:00:00.000Z",
  "currency": "USD",
  "timezone": "America/New_York",
  "total_cents": 184200,
  "budget": {
    "monthly_cap_cents": 500000,
    "daily_cap_cents": 50000,
    "channel_thresholds": { "voice": 50000 },
    "alert_at_percent": 80
  },
  "features": [
    { "channel": "voice", "total_cost_cents": 92000, "total_tokens": 1840000, "event_count": 3201 },
    { "channel": "inbox", "total_cost_cents": 61200, "total_tokens": 1120000, "event_count": 2104 }
  ],
  "threshold_breaches": [
    { "channel": "voice", "cents": 92000, "threshold_cents": 50000, "percent": 184.0 }
  ]
}

Budget

GET /api/v1/insights/llm-spend/budget returns the current AI budget config. PUT updates it. All body fields are optional — omitted fields keep their current value (read-merge-write), and the server re-validates on write, so out-of-range values are dropped rather than persisted.

Field	Type	Notes
`monthly_cap_cents`	integer \| `null`	Monthly cap. `null` clears it. Max 100,000,000,000
`daily_cap_cents`	integer \| `null`	Hard per-day cap, drives the overview cap ring. `null` clears it
`channel_thresholds`	object	Per-channel caps in cents, keyed by channel slug (e.g. `{ "voice": 50000 }`)
`alert_at_percent`	integer	Soft-alert threshold, 1-100. Defaults to 80

PUT a settings body:

curl -X PUT https://api.orbit.devotel.io/api/v1/insights/llm-spend/budget \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monthly_cap_cents": 500000, "daily_cap_cents": 50000, "channel_thresholds": { "voice": 50000 }, "alert_at_percent": 80 }'

import requests
r = requests.put(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/budget",
    headers={"X-API-Key": ORBIT_API_KEY},
    json={
        "monthly_cap_cents": 500000,
        "daily_cap_cents": 50000,
        "channel_thresholds": {"voice": 50000},
        "alert_at_percent": 80,
    },
)
print(r.json()["data"])

{
  "monthly_cap_cents": 500000,
  "daily_cap_cents": 50000,
  "channel_thresholds": { "voice": 50000 },
  "alert_at_percent": 80
}

Then GET to echo the saved state:

curl https://api.orbit.devotel.io/api/v1/insights/llm-spend/budget \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/llm-spend/budget",
    headers={"X-API-Key": ORBIT_API_KEY},
)
print(r.json()["data"])

{
  "monthly_cap_cents": 500000,
  "daily_cap_cents": 50000,
  "channel_thresholds": { "voice": 50000 },
  "alert_at_percent": 80
}

Agent ROI

Attributes outcome revenue to each agent and reports cost, attributed revenue, and margin.

Method	Path	Purpose
`GET`	`/api/v1/insights/agent-roi`	Per-agent cost, attributed revenue, and margin + org totals
`GET`	`/api/v1/insights/agent-roi/timeseries`	Daily cost / revenue / margin trend
`GET`	`/api/v1/insights/agent-roi/config`	Current attribution config
`PUT`	`/api/v1/insights/agent-roi/config`	Update the attribution config

curl "https://api.orbit.devotel.io/api/v1/insights/agent-roi?from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/agent-roi",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"from": "2026-07-01T00:00:00Z", "to": "2026-08-01T00:00:00Z"},
)
for a in r.json()["data"]["agents"]:
    print(a["agent_name"], a["margin_percent"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "currency": "USD",
  "timezone": "America/New_York",
  "config": {
    "default_outcome_value_cents": 5000,
    "per_rubric_value_cents": { "rub_order_complete": 12400 }
  },
  "totals": {
    "cost_cents": 81200,
    "attributed_revenue_cents": 391000,
    "margin_cents": 309800,
    "margin_percent": 79.2,
    "outcomes_count": 66,
    "conversation_count": 4180,
    "agent_count": 3,
    "shown_count": 3,
    "truncated": false
  },
  "agents": [
    {
      "agent_id": "ag_sales_assist",
      "agent_name": "Sales assist",
      "model": "acme/reasoning-large",
      "cost_cents": 42300,
      "attributed_revenue_cents": 288000,
      "margin_cents": 245700,
      "margin_percent": 85.3,
      "outcomes_count": 41,
      "conversation_count": 1870,
      "outcomes": [
        {
          "rubric_id": "rub_order_complete",
          "rubric_name": "Order complete",
          "passed_count": 23,
          "value_cents": 12400,
          "subtotal_cents": 285200
        }
      ]
    }
  ]
}

A negative margin_cents means the agent runs at a loss for the window; margin_percent is null when attributed revenue is zero. totals.truncated is true when more agents than your limit had traffic — raise limit (max 200) or treat the page as a preview. GET /agent-roi/timeseries accepts from, to, and an optional agentId to scope the trend to a single agent:

curl "https://api.orbit.devotel.io/api/v1/insights/agent-roi/timeseries?agentId=ag_sales_assist&from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/agent-roi/timeseries",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={
        "agentId": "ag_sales_assist",
        "from": "2026-07-01T00:00:00Z",
        "to": "2026-08-01T00:00:00Z",
    },
)
for day in r.json()["data"]["series"]:
    print(day["bucket"], day["margin_cents"])

{
  "agent_id": "ag_sales_assist",
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "series": [
    { "bucket": "2026-07-01", "cost_cents": 1420, "attributed_revenue_cents": 8200, "margin_cents": 6780 },
    { "bucket": "2026-07-02", "cost_cents": 1510, "attributed_revenue_cents": 9640, "margin_cents": 8130 }
  ]
}

Attribution is driven by a value-per-outcome config. PUT /agent-roi/config is a read-merge-write with two optional fields:

Field	Type	Notes
`default_outcome_value_cents`	integer \| `null`	Default revenue value per attributed outcome. `null` clears it
`per_rubric_value_cents`	object	Per-rubric value overrides in cents, keyed by rubric id (max 500 entries)

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": 5000, "per_rubric_value_cents": { "rub_order_complete": 12400 } }'

import requests
r = requests.put(
    "https://api.orbit.devotel.io/api/v1/insights/agent-roi/config",
    headers={"X-API-Key": ORBIT_API_KEY},
    json={
        "default_outcome_value_cents": 5000,
        "per_rubric_value_cents": {"rub_order_complete": 12400},
    },
)
print(r.json()["data"])

{
  "default_outcome_value_cents": 5000,
  "per_rubric_value_cents": { "rub_order_complete": 12400 }
}

Containment & resolution

Reports how often agents handle a conversation without a human handoff (containment), how often a conversation reaches a resolved status or passes a rubric outcome (resolution), and how often it escalates.

Method	Path	Purpose
`GET`	`/api/v1/insights/containment`	Per-agent containment, resolution, and escalation rates + org totals
`GET`	`/api/v1/insights/containment/timeseries`	Daily containment / resolution trend

GET /containment accepts from, to, and limit (default 50, max 200). GET /containment/timeseries accepts from, to, and an optional agentId.

curl "https://api.orbit.devotel.io/api/v1/insights/containment?from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/containment",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"from": "2026-07-01T00:00:00Z", "to": "2026-08-01T00:00:00Z"},
)
print(r.json()["data"]["totals"]["containment_rate"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "timezone": "America/New_York",
  "totals": {
    "total_conversations": 4180,
    "handed_off_count": 1012,
    "contained_count": 3168,
    "resolved_count": 2921,
    "containment_rate": 75.8,
    "escalation_rate": 24.2,
    "resolution_rate": 69.9,
    "agent_count": 3
  },
  "agents": [
    {
      "agent_id": "ag_sales_assist",
      "agent_name": "Sales assist",
      "model": "acme/reasoning-large",
      "total_conversations": 1870,
      "handed_off_count": 351,
      "contained_count": 1519,
      "resolved_count": 1394,
      "containment_rate": 81.2,
      "resolution_rate": 74.6
    }
  ]
}

Containment asks “did this conversation stay with the agent?”; resolution asks “did it reach a resolved status or pass a rubric outcome?”. Promote on both, not just the first.

Agent comparison & benchmarks

Ranks agents against each other and against the org baseline on the KPIs already computed above (cost, attributed revenue, margin, containment, resolution, escalation).

Method	Path	Purpose
`GET`	`/api/v1/insights/agent-comparison`	Flat KPI table for a chosen set of agents + an org-average baseline
`GET`	`/api/v1/insights/agent-benchmarks`	Per-metric percentile, rank, and band for each agent vs the org population

Param	Type	Notes
`from`	ISO 8601	Window start (defaults to last 30 days)
`to`	ISO 8601	Window end (defaults to now)
`agentIds`	string	Comma-separated agent ids. Required for `agent-comparison` (2-200 ids). Optional for `agent-benchmarks` — omit to benchmark every agent with traffic

agent-comparison needs at least two ids; the response adds the full-org org_average row, the KPI metric catalogue (key, label, unit, higherIsBetter), and population-safety flags (population_size, ranked_population_size, population_truncated). When population_truncated is true, the averages and badges reflect the top-by-traffic subset, not every agent.

curl "https://api.orbit.devotel.io/api/v1/insights/agent-comparison?agentIds=ag_sales_assist,ag_support_front&from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/agent-comparison",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={
        "agentIds": "ag_sales_assist,ag_support_front",
        "from": "2026-07-01T00:00:00Z",
        "to": "2026-08-01T00:00:00Z",
    },
)
print(r.json()["data"]["org_average"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "currency": "USD",
  "timezone": "America/New_York",
  "metrics": [
    { "key": "containment_rate", "label": "Containment %", "unit": "percent", "higherIsBetter": true },
    { "key": "resolution_rate", "label": "Resolution %", "unit": "percent", "higherIsBetter": true },
    { "key": "escalation_rate", "label": "Escalation %", "unit": "percent", "higherIsBetter": false },
    { "key": "cost_cents", "label": "Cost", "unit": "cents", "higherIsBetter": false },
    { "key": "attributed_revenue_cents", "label": "Attributed revenue", "unit": "cents", "higherIsBetter": true },
    { "key": "margin_cents", "label": "Margin", "unit": "cents", "higherIsBetter": true },
    { "key": "margin_percent", "label": "Margin %", "unit": "percent", "higherIsBetter": true }
  ],
  "population_size": 3,
  "ranked_population_size": 3,
  "population_truncated": false,
  "org_average": {
    "containment_rate": 71.4,
    "resolution_rate": 63.8,
    "escalation_rate": 28.6,
    "cost_cents": 27100,
    "attributed_revenue_cents": 130400,
    "margin_cents": 103300,
    "margin_percent": 61.5
  },
  "agents": [
    {
      "agent_id": "ag_sales_assist",
      "agent_name": "Sales assist",
      "model": "acme/reasoning-large",
      "conversation_count": 1870,
      "cost_cents": 42300,
      "attributed_revenue_cents": 288000,
      "margin_cents": 245700,
      "margin_percent": 85.3,
      "containment_rate": 81.2,
      "resolution_rate": 74.6,
      "escalation_rate": 18.8
    },
    {
      "agent_id": "ag_support_front",
      "agent_name": "Support front line",
      "model": "acme/reasoning-small",
      "conversation_count": 2310,
      "cost_cents": 38900,
      "attributed_revenue_cents": 103000,
      "margin_cents": 64100,
      "margin_percent": 62.2,
      "containment_rate": 64.1,
      "resolution_rate": 58.3,
      "escalation_rate": 35.9
    }
  ]
}

Each agent row carries agent_id, agent_name, model, conversation_count, cost_cents, attributed_revenue_cents, margin_cents, margin_percent, containment_rate, resolution_rate, and escalation_rate. Rate fields are 1-decimal percentages or null when the denominator is zero; unknown ids are silently dropped, so diff the returned rows against the ids you sent. agent-benchmarks ranks every agent with traffic across percentile bands:

curl "https://api.orbit.devotel.io/api/v1/insights/agent-benchmarks?from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/agent-benchmarks",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"from": "2026-07-01T00:00:00Z", "to": "2026-08-01T00:00:00Z"},
)
print(r.json()["data"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "agents": [
    {
      "agent_id": "ag_sales_assist",
      "agent_name": "Sales assist",
      "benchmarks": [
        { "metric": "containment_rate", "value": 81.2, "percentile": 92, "rank": 1, "band": "top" },
        { "metric": "margin_percent", "value": 85.3, "percentile": 88, "rank": 1, "band": "top" }
      ]
    }
  ]
}

Cost economics

One cross-channel view of what usage costs and what each unit costs you. It prices per-message (SMS, WhatsApp), per-minute (voice, video), and per-1,000-token (AI) usage at configurable rates, then rolls everything into per-channel cost, a per-channel per-unit cost, and blended totals. Use it to compare unit economics across channels instead of reading each channel’s ledger on its own.

Method	Path	Purpose
`GET`	`/api/v1/insights/cost-economics`	Per-channel usage, cost, and per-unit cost + blended totals
`GET`	`/api/v1/insights/cost-economics/config`	Current per-unit rate config
`PUT`	`/api/v1/insights/cost-economics/config`	Update the per-unit rate config

GET /cost-economics accepts from and to (defaults to the last 30 days, capped at 365). The response carries the current config, the applied rates (your configured values, or the platform defaults where you haven’t set one), a channels array with one row per channel (channel, volume, cost_cents, per_unit_cost_cents), and totals (cost_cents, message_volume, voice_minutes, ai_tokens). per_unit_cost_cents is null when the channel had zero volume in the window — read it as “no usage”, not “free”.

curl "https://api.orbit.devotel.io/api/v1/insights/cost-economics?from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
  -H "X-API-Key: $ORBIT_API_KEY"

import requests
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/insights/cost-economics",
    headers={"X-API-Key": ORBIT_API_KEY},
    params={"from": "2026-07-01T00:00:00Z", "to": "2026-08-01T00:00:00Z"},
)
for ch in r.json()["data"]["channels"]:
    print(ch["channel"], ch["per_unit_cost_cents"])

{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-08-01T00:00:00.000Z",
  "currency": "USD",
  "timezone": "America/New_York",
  "config": {
    "sms_per_message_cents": 2,
    "whatsapp_per_message_cents": null,
    "voice_per_minute_cents": 12,
    "ai_per_1000_tokens_cents": null,
    "video_per_minute_cents": null
  },
  "applied": {
    "sms_per_message_cents": 2,
    "whatsapp_per_message_cents": 3,
    "voice_per_minute_cents": 12,
    "ai_per_1000_tokens_cents": 1,
    "video_per_minute_cents": 20
  },
  "channels": [
    { "channel": "sms", "volume": 18200, "cost_cents": 36400, "per_unit_cost_cents": 2 },
    { "channel": "whatsapp", "volume": 9100, "cost_cents": 27300, "per_unit_cost_cents": 3 },
    { "channel": "voice", "volume": 3200, "cost_cents": 38400, "per_unit_cost_cents": 12 },
    { "channel": "ai", "volume": 5200000, "cost_cents": 5200, "per_unit_cost_cents": 1 },
    { "channel": "video", "volume": 0, "cost_cents": 0, "per_unit_cost_cents": null }
  ],
  "totals": {
    "cost_cents": 107300,
    "message_volume": 27300,
    "voice_minutes": 3200,
    "ai_tokens": 5200000
  }
}

AI volume is raw tokens (volume), priced per 1,000 tokens (ai_per_1000_tokens_cents). totals.message_volume sums SMS + WhatsApp messages, totals.voice_minutes sums voice + video minutes, and totals.ai_tokens reports AI volume separately since its basis differs. PUT /cost-economics/config is a read-merge-write: every field is optional and keeps its current value when omitted; an explicit null resets that rate back to the platform default. Values are integer cents, minimum 0, maximum 100,000,000,000.

Field	Type	Notes
`sms_per_message_cents`	integer \| `null`	Per-SMS-message rate. `null` resets to default
`whatsapp_per_message_cents`	integer \| `null`	Per-WhatsApp-message rate. `null` resets to default
`voice_per_minute_cents`	integer \| `null`	Per-voice-minute rate. `null` resets to default
`ai_per_1000_tokens_cents`	integer \| `null`	Per-1,000-token AI rate. `null` resets to default
`video_per_minute_cents`	integer \| `null`	Per-video-minute rate. `null` resets to default

curl -X PUT https://api.orbit.devotel.io/api/v1/insights/cost-economics/config \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voice_per_minute_cents": 10, "video_per_minute_cents": null }'

import requests
r = requests.put(
    "https://api.orbit.devotel.io/api/v1/insights/cost-economics/config",
    headers={"X-API-Key": ORBIT_API_KEY},
    json={"voice_per_minute_cents": 10, "video_per_minute_cents": None},
)
print(r.json()["data"])

{
  "sms_per_message_cents": 2,
  "whatsapp_per_message_cents": null,
  "voice_per_minute_cents": 10,
  "ai_per_1000_tokens_cents": null,
  "video_per_minute_cents": null
}

Compute LLM margin

One line of math joins the ROI rollup to the LLM-spend tracker: revenue minus model spend. Three steps:

GET /api/v1/insights/llm-spend/overview → take month_to_date.spend_cents (your AI run-cost).
GET /api/v1/insights/agent-roi → sum totals.attributed_revenue_cents over the same window.
Compute margin: attributed_revenue_cents - spend_cents, and margin % as ratio of revenue.

Python

import requests
headers = {"X-API-Key": ORBIT_API_KEY}
base = "https://api.orbit.devotel.io/api/v1/insights"

spend = requests.get(f"{base}/llm-spend/overview", headers=headers).json()["data"]["month_to_date"]["spend_cents"]
revenue = requests.get(f"{base}/agent-roi", headers=headers).json()["data"]["totals"]["attributed_revenue_cents"]

margin = revenue - spend
margin_pct = round(100 * margin / revenue, 1) if revenue else None
print(f"Month-to-date LLM margin: {margin} cents ({margin_pct}%)")

Cost and containment settings are tenant-owned: they apply only inside your organization and are never shared across customers.

API Reference

All Endpoints

Insights API: AI agent cost, ROI, and containment

Insights API

Using the SDKs

Conventions

LLM spend

Overview

Summary

Timeseries

Top conversations

By feature

Budget

Agent ROI

Containment & resolution

Agent comparison & benchmarks

Cost economics

Compute LLM margin

See also

​Insights API

​Using the SDKs

​Conventions

​LLM spend

​Overview

​Summary

​Timeseries

​Top conversations

​By feature

​Budget

​Agent ROI

​Containment & resolution

​Agent comparison & benchmarks

​Cost economics

​Compute LLM margin

​See also

Insights API

Using the SDKs

Conventions

LLM spend

Overview

Summary

Timeseries

Top conversations

By feature

Budget

Agent ROI

Containment & resolution

Agent comparison & benchmarks

Cost economics

Compute LLM margin

See also