Worked insights queries

Every operation below is catalogued on this page, but the values you branch on — a spend spike’s driver, a containment trend, an anomaly scope — are easiest to learn as reader chains. The chains below answer a real operator question end to end and show the exact { data, meta } envelope at each step so you can slice the field path you actually need. Scope of this overlay:

The chains cover six questions against the Insights catalogue; each one starts from the broad read, then narrows with a follow-up call. Where a dashboard guide exists, the overlay links it rather than repeat it.
All samples show cURL and TypeScript — the generated operations above show all six languages on the first 15 blocks, cURL and TypeScript on the rest.
All reads are tenant-scoped, read-only analytic aggregates over your own data. No provider account or compliance scope is touched; the tenant controls every filter, window, and scope parameter.

All Insights envelope responses share one shape: data carries the payload, meta.request_id and meta.timestamp identify the read. Chain on data, log meta.request_id when you report a discrepancy to support.

1. Which model drove the LLM spend spike

Start from the period summary, drill into the breakdown by model, then confirm against cost-economics so you see spend in the same window as your other AI economics. GET /api/v1/insights/llm-spend/summary

curl -G "https://api.orbit.devotel.io/api/v1/insights/llm-spend/summary" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "window_days=7"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/llm-spend/summary",
);
url.searchParams.set("window_days", "7");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.total_cents);

200

{
  "data": {
    "total_cents": 41250,
    "currency": "USD",
    "window_days": 7,
    "by_model_top": "gpt-5-thinking",
    "by_feature_top": "support_agent"
  },
  "meta": { "request_id": "req_llm_01", "timestamp": "2026-09-09T12:00:00.000Z" }
}

Now drill into the driver. GET /api/v1/insights/llm-spend/by-model breaks spend per model; GET /api/v1/insights/llm-spend/by-feature breaks it per feature surface. Slice data.models[] (or data.features[]) for the rows that moved.

curl -G "https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-model" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "window_days=7"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-model",
);
url.searchParams.set("window_days", "7");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.models.map((m) => `${m.model}: ${m.cents}`));

200

{
  "data": {
    "models": [
      { "model": "gpt-5-thinking", "cents": 30112, "share_pct": 73.0 },
      { "model": "claude-opus", "cents": 7214, "share_pct": 17.5 },
      { "model": "gpt-5-mini", "cents": 3924, "share_pct": 9.5 }
    ],
    "window_days": 7
  },
  "meta": { "request_id": "req_llm_02", "timestamp": "2026-09-09T12:00:01.000Z" }
}

Put the spend in the same window as your AI economics: GET /api/v1/insights/cost-economics returns the platform side (provider and inference cost per conversation) so you can reconcile the spike against what those conversations actually cost the whole platform, not only the model tier.

curl -G "https://api.orbit.devotel.io/api/v1/insights/cost-economics" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "window_days=7"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/cost-economics",
);
url.searchParams.set("window_days", "7");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.avg_cost_per_conversation_cents);

200

{
  "data": {
    "avg_cost_per_conversation_cents": 3.7,
    "window_days": 7,
    "conversation_count": 11148
  },
  "meta": { "request_id": "req_llm_03", "timestamp": "2026-09-09T12:00:02.000Z" }
}

2. Compare anomaly scopes and page history rollups

The anomaly surface answers “where did the spike come from?” — GET /api/v1/insights/anomaly-insights/by-scope ranks the affected scopes (feature, model, agent, channel) so you slice against the right dimension before paging the ledger.

curl -G "https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/by-scope" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "window_days=30"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/by-scope",
);
url.searchParams.set("window_days", "30");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.scopes.map((s) => `${s.scope}: ${s.top_value}`));

200

{
  "data": {
    "scopes": [
      { "scope": "feature", "top_value": "support_agent", "open_count": 3 },
      { "scope": "model", "top_value": "gpt-5-thinking", "open_count": 3 }
    ],
    "window_days": 30
  },
  "meta": { "request_id": "req_an_01", "timestamp": "2026-09-09T12:00:03.000Z" }
}

Page the anomaly ledger — GET /api/v1/insights/anomaly-insights/history returns a cursor-paged list. Pass the previous page’s next token back as cursor until it comes back null.

curl -G "https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/history" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "limit=10" \
  --data-urlencode "cursor=an_219"

const all = [];
let cursor: string | undefined;
do {
  const url = new URL(
    "https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/history",
  );
  url.searchParams.set("limit", "10");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  });
  const body = await res.json();
  all.push(...body.data.items);
  cursor = body.data.next ?? undefined;
} while (cursor);

200

{
  "data": {
    "items": [
      {
        "id": "an_219",
        "scope": "model",
        "value": "gpt-5-thinking",
        "metric": "cents",
        "severity": "high",
        "start_ts": "2026-09-02T14:00:00.000Z",
        "status": "resolved"
      }
    ],
    "next": null
  },
  "meta": { "request_id": "req_an_02", "timestamp": "2026-09-09T12:00:04.000Z" }
}

3. Benchmark and QA sample queries

Score before/after comparisons on a benchmark — GET /api/v1/insights/ agent-benchmarks returns a ranked list of quality/funnel scores so you compare two AI agents, two model versions, or your agent against a human queue.

curl -G "https://api.orbit.devotel.io/api/v1/insights/agent-benchmarks" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "metric=resolution_rate"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/agent-benchmarks",
);
url.searchParams.set("metric", "resolution_rate");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.benchmarks.map((b) => `${b.name}: ${b.score}`));

200

{
  "data": {
    "benchmarks": [
      { "name": "support_v2", "score": 87.4, "baseline": 84.1 },
      { "name": "support_v1", "score": 84.1, "baseline": 84.1 }
    ],
    "metric": "resolution_rate"
  },
  "meta": { "request_id": "req_qa_01", "timestamp": "2026-09-09T12:00:05.000Z" }
}

For QA follow-ups, the GET /api/v1/insights/agent-quality/by-language endpoint breaks the same score down per conversation language, and GET /api/v1/insights/language-quality ranks phrasing/coverage issues — slice data.rows[] to the sample conversations you want to re-check.

4. Attribution: funnel steps → journey paths → conversion goal

Attribution chains answer “which step dropped the funnel?” — GET /api/v1/insights/call-attribution attributes conversion credit to call and message touches, GET /api/v1/insights/automation-opportunities ranks the funnel steps where automation covers the drop, and GET /api/v1/insights/agent-roi/timeseries trends goal conversion over the window.

curl -G "https://api.orbit.devotel.io/api/v1/insights/call-attribution" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "goal=demo_booked" \
  --data-urlencode "window_days=30"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/call-attribution",
);
url.searchParams.set("goal", "demo_booked");
url.searchParams.set("window_days", "30");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.touches.map((t) => `${t.step}: ${t.credit_pct}%`));

200

{
  "data": {
    "goal": "demo_booked",
    "touches": [
      { "step": "sms_reminder", "credit_pct": 41.2 },
      { "step": "call_back", "credit_pct": 33.9 },
      { "step": "ai_agent_followup", "credit_pct": 24.9 }
    ],
    "window_days": 30
  },
  "meta": { "request_id": "req_at_01", "timestamp": "2026-09-09T12:00:06.000Z" }
}

Drill into the step that dropped with GET /api/v1/insights/automation- opportunities — it returns candidate funnel steps ranked by the recoverable volume per step.

200

{
  "data": {
    "opportunities": [
      {
        "step": "call_back",
        "recoverable_pct": 18.5,
        "note": "frequent drop after hold"
      }
    ]
  },
  "meta": { "request_id": "req_at_02", "timestamp": "2026-09-09T12:00:07.000Z" }
}

Trend the goal with GET /api/v1/insights/agent-roi/timeseries — data.points[] carries the per-bucket conversion so you can chart the recovery against the anomaly window you paged in chain 2.

5. Containment trend + talk ratio

Containment answers “how many conversations resolve without a human?” — GET /api/v1/insights/containment returns the current rate, then GET /api/v1/insights/containment/timeseries trends the same metric over the window so you see whether a prompt or KB change moved it.

curl -G "https://api.orbit.devotel.io/api/v1/insights/containment" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/containment",
);
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.containment_pct);

200

{
  "data": { "containment_pct": 71.4, "conversation_count": 11148 },
  "meta": { "request_id": "req_ct_01", "timestamp": "2026-09-09T12:00:08.000Z" }
}

curl -G "https://api.orbit.devotel.io/api/v1/insights/containment/timeseries" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "window_days=30" \
  --data-urlencode "bucket=day"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/containment/timeseries",
);
url.searchParams.set("window_days", "30");
url.searchParams.set("bucket", "day");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.points.map((p) => `${p.bucket_date}: ${p.containment_pct}`));

200

{
  "data": {
    "points": [
      { "bucket_date": "2026-08-11", "containment_pct": 68.9 },
      { "bucket_date": "2026-08-12", "containment_pct": 69.7 },
      { "bucket_date": "2026-08-13", "containment_pct": 71.4 }
    ],
    "bucket": "day"
  },
  "meta": { "request_id": "req_ct_02", "timestamp": "2026-09-09T12:00:09.000Z" }
}

6. Quality eval scores

Voice and conversation quality evals answer “is the agent answering well?” — GET /api/v1/insights/sales-conversation-intelligence returns the latest scored conversations and their eval dimensions (rapport, coverage, objection handling). Pair with GET /api/v1/insights/containment from chain 5 to see whether a low eval score also pushed the transfer rate up.

curl -G "https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "limit=5"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence",
);
url.searchParams.set("limit", "5");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.rows.map((r) => `${r.conversation_id}: ${r.score}`));

200

{
  "data": {
    "rows": [
      {
        "conversation_id": "conv_8a2f",
        "score": 83.5,
        "rapport": 88.1,
        "coverage": 81.2,
        "objection_handling": 80.1
      }
    ],
    "limit": 5
  },
  "meta": { "request_id": "req_ev_01", "timestamp": "2026-09-09T12:00:10.000Z" }
}

Pagination and envelope rules

Cursor pages. Ledger-style list endpoints return data.items + data.next. Pass cursor=<next> to fetch the following page; null terminates the sequence. Page size defaults are stated on each operation; keep the same filters across pages.
Slice fields. Filter parameters are the tenant surface: window_days, metric, scope, goal, bucket. Chain 2 shows the cursor loop; every other chain shows the filter-slice.
The { data, meta } envelope. Branch on data; log meta.request_id when a value looks wrong — support can replay it.

The dashboard views and per-surface readings live in Insight dashboards, Real-time analytics, Insight costs, and the LLM spend guide. This overlay is envelope-accurate: request, response, and the drill-in call — nothing else.

For the dashboard-side walkthrough of the surfaces these endpoints feed, see the Insights guides. Compliance notes: every filter and scope on this page is a tenant-owned control — nothing here touches provider account scope or sends traffic.

API Reference

All Endpoints

Worked insights queries