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 two PUT endpoints (budget and ROI config) 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.

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 returns 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. cap_percentage, projected_month_end_cents, and vs_last_period_percent are null when there’s no cap configured or no historic spend to project from.

{
  "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

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)

Returns totals for the whole window plus a groups array, each row carrying group_id, group_label, model, total_tokens, total_cost_cents, and conversation_count, ordered by cost descending.

Timeseries

GET /api/v1/insights/llm-spend/timeseries

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.

Top conversations

GET /api/v1/insights/llm-spend/top-conversations

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)

Returns a conversations array of the most expensive threads, each with conversation_id, agent_id, agent_name, model, total_tokens, total_cost_cents, and started_at for drill-down.

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.

{
  "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

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 '{ "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

GET /agent-roi accepts from, to, and limit (default 50, max 200). GET /agent-roi/timeseries accepts from, to, and an optional agentId to scope the trend to a single agent. 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)

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.

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

API Reference

All Endpoints

Insights API

Insights API

Conventions

LLM spend

Overview

Summary

Timeseries

Top conversations

By feature

Budget

Agent ROI

Containment & resolution

Agent comparison & benchmarks

See also

​Insights API

​Conventions

​LLM spend

​Overview

​Summary

​Timeseries

​Top conversations

​By feature

​Budget

​Agent ROI

​Containment & resolution

​Agent comparison & benchmarks

​See also

Insights API

Conventions

LLM spend

Overview

Summary

Timeseries

Top conversations

By feature

Budget

Agent ROI

Containment & resolution

Agent comparison & benchmarks

See also