{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "currency": "USD",
    "timezone": "UTC",
    "metrics": [
      {
        "key": "containment_rate",
        "label": "Containment rate",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "resolution_rate",
        "label": "Resolution rate",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "cost_cents",
        "label": "Cost",
        "unit": "cents",
        "higherIsBetter": false
      },
      {
        "key": "margin_percent",
        "label": "Margin",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "attributed_revenue_cents",
        "label": "Attributed revenue",
        "unit": "cents",
        "higherIsBetter": true
      },
      {
        "key": "margin_cents",
        "label": "Margin absolute",
        "unit": "cents",
        "higherIsBetter": true
      },
      {
        "key": "escalation_rate",
        "label": "Escalation rate",
        "unit": "percent",
        "higherIsBetter": false
      }
    ],
    "population_size": 4,
    "ranked_population_size": 4,
    "population_truncated": false,
    "org_average": {
      "cost_cents": 10421,
      "attributed_revenue_cents": 214500,
      "margin_cents": 204079,
      "margin_percent": 95.1,
      "containment_rate": 74.3,
      "resolution_rate": 69.8,
      "escalation_rate": 25.7
    },
    "agents": [
      {
        "agent_id": "agt_01JAQ2K8PF4X",
        "agent_name": "Support Intake",
        "model": "gpt-5-thinking",
        "conversation_count": 1284,
        "benchmarks": {
          "cost_cents": {
            "value": 10421,
            "org_average": 10421,
            "percentile": 62.1,
            "rank": 2,
            "sample_size": 4,
            "band": "above_average"
          },
          "attributed_revenue_cents": {
            "value": 214500,
            "org_average": 214500,
            "percentile": 88.4,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "margin_cents": {
            "value": 204079,
            "org_average": 204079,
            "percentile": 88.4,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "margin_percent": {
            "value": 95.1,
            "org_average": 95.1,
            "percentile": 75.2,
            "rank": 2,
            "sample_size": 4,
            "band": "above_average"
          },
          "containment_rate": {
            "value": 74.3,
            "org_average": 74.3,
            "percentile": 88.4,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "resolution_rate": {
            "value": 69.8,
            "org_average": 69.8,
            "percentile": 81.7,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "escalation_rate": {
            "value": 25.7,
            "org_average": 25.7,
            "percentile": 18.9,
            "rank": 4,
            "sample_size": 4,
            "band": "bottom_quartile"
          }
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "currency": "USD",
    "timezone": "UTC",
    "metrics": [
      {
        "key": "containment_rate",
        "label": "Containment rate",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "resolution_rate",
        "label": "Resolution rate",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "cost_cents",
        "label": "Cost",
        "unit": "cents",
        "higherIsBetter": false
      },
      {
        "key": "margin_percent",
        "label": "Margin",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "attributed_revenue_cents",
        "label": "Attributed revenue",
        "unit": "cents",
        "higherIsBetter": true
      },
      {
        "key": "margin_cents",
        "label": "Margin absolute",
        "unit": "cents",
        "higherIsBetter": true
      },
      {
        "key": "escalation_rate",
        "label": "Escalation rate",
        "unit": "percent",
        "higherIsBetter": false
      }
    ],
    "population_size": 4,
    "ranked_population_size": 4,
    "population_truncated": false,
    "org_average": {
      "cost_cents": 10421,
      "attributed_revenue_cents": 214500,
      "margin_cents": 204079,
      "margin_percent": 95.1,
      "containment_rate": 74.3,
      "resolution_rate": 69.8,
      "escalation_rate": 25.7
    },
    "agents": [
      {
        "agent_id": "agt_01JAQ2K8PF4X",
        "agent_name": "Support Intake",
        "model": "gpt-5-thinking",
        "conversation_count": 1284,
        "benchmarks": {
          "cost_cents": {
            "value": 10421,
            "org_average": 10421,
            "percentile": 62.1,
            "rank": 2,
            "sample_size": 4,
            "band": "above_average"
          },
          "attributed_revenue_cents": {
            "value": 214500,
            "org_average": 214500,
            "percentile": 88.4,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "margin_cents": {
            "value": 204079,
            "org_average": 204079,
            "percentile": 88.4,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "margin_percent": {
            "value": 95.1,
            "org_average": 95.1,
            "percentile": 75.2,
            "rank": 2,
            "sample_size": 4,
            "band": "above_average"
          },
          "containment_rate": {
            "value": 74.3,
            "org_average": 74.3,
            "percentile": 88.4,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "resolution_rate": {
            "value": 69.8,
            "org_average": 69.8,
            "percentile": 81.7,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "escalation_rate": {
            "value": 25.7,
            "org_average": 25.7,
            "percentile": 18.9,
            "rank": 4,
            "sample_size": 4,
            "band": "bottom_quartile"
          }
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Insights API

Insights endpoints exposed by the Devotel CPaaS API Base path: /api/v1/insights Endpoint count: 42

title: “Worked insights queries” description: “LLM-spend drill-downs, anomaly rollups, agent benchmarks, attribution chains, containment trends, and quality evals — each as a full send → envelope → drill-in chain.”

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:

Chains 1–6 cover the most-used reads head-first. Chains 7–11 pick up the GET operations those chains did not name — the remaining LLM-spend reads (overview, timeseries, top-conversations, by-feature, by-model, budget, model-caps), the agent comparison and per-language quality reads, and conversation P&L — each with the same send → envelope → drill-in shape.
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.
Samples use a sandbox key (dv_test_sk_your_test_key_here). A test-prefixed key unconditionally runs in sandbox and deducts no credits; swap to your dv_live_sk_* key in production. See Sandbox.
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. The worked envelopes below use req_insights_* placeholders — a real response returns a server-issued id in the same shape.

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_test_sk_your_test_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_insights_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_test_sk_your_test_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_insights_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_test_sk_your_test_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_insights_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_test_sk_your_test_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_insights_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_test_sk_your_test_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_insights_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_test_sk_your_test_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_insights_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_test_sk_your_test_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_insights_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_insights_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_test_sk_your_test_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_insights_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_test_sk_your_test_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_insights_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. For segment-level eval detail, follow with GET /api/v1/insights/agent-quality/by-language (chain 8) — it breaks rubric pass-rate, containment, and sentiment down per detected language so you can isolate a quality gap to one locale.

curl -G "https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence" \
  -H "X-API-Key: dv_test_sk_your_test_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_insights_ev_01", "timestamp": "2026-09-09T12:00:10.000Z" }
}

7. Read the LLM-spend header, trend, and leaderboard

The LLM-spend header chain answers “where do I stand right now?” — the chain 1 aggregates answered “what drove the spike?”; this one reads the header cards, the trend buckets, and the expensive-conversation leaderboard that the overview page renders. Start with the header: GET /api/v1/insights/llm-spend/overview returns today’s spend, the month-to-date total with a month-end projection, and the trailing-7-day average — three fields intentionally return null when a value is not computable (no daily cap configured, no prior-period baseline, no spend history), so branch on null before you chart.

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

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/insights/llm-spend/overview",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const body = await res.json();
console.log(body.data.today.spend_cents, body.data.month_to_date.spend_cents);

200

{
  "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
  },
  "meta": { "request_id": "req_insights_ov_01", "timestamp": "2026-09-09T12:00:11.000Z" }
}

Trend it with GET /api/v1/insights/llm-spend/timeseries — bucketed hourly or daily, in the org’s billing timezone:

curl -G "https://api.orbit.devotel.io/api/v1/insights/llm-spend/timeseries" \
  -H "X-API-Key: dv_test_sk_your_test_key_here" \
  --data-urlencode "granularity=day" \
  --data-urlencode "from=2026-09-01T00:00:00Z" \
  --data-urlencode "to=2026-09-09T00:00:00Z"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/llm-spend/timeseries",
);
url.searchParams.set("granularity", "day");
url.searchParams.set("from", "2026-09-01T00:00:00Z");
url.searchParams.set("to", "2026-09-09T00:00:00Z");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.series.map((s) => `${s.bucket}: ${s.total_cost_cents}`));

200

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-09T00:00:00.000Z",
    "granularity": "day",
    "currency": "USD",
    "timezone": "America/New_York",
    "series": [
      { "bucket": "2026-09-01T00:00:00", "total_tokens": 590000, "total_cost_cents": 11800 },
      { "bucket": "2026-09-02T00:00:00", "total_tokens": 615000, "total_cost_cents": 12410 }
    ]
  },
  "meta": { "request_id": "req_insights_ov_02", "timestamp": "2026-09-09T12:00:12.000Z" }
}

Find where the spend concentrates with GET /api/v1/insights/llm-spend/top-conversations — a per-conversation leaderboard for the window, cheapest drill for “one thread ate my budget”:

curl -G "https://api.orbit.devotel.io/api/v1/insights/llm-spend/top-conversations" \
  -H "X-API-Key: dv_test_sk_your_test_key_here" \
  --data-urlencode "limit=5"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/llm-spend/top-conversations",
);
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.conversations.map((c) => `${c.conversation_id}: ${c.total_cost_cents}`));

200

{
  "data": {
    "from": "2026-08-10T00:00:00.000Z",
    "to": "2026-09-09T00: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": 812000,
        "total_cost_cents": 16240,
        "started_at": "2026-09-04T15:20:00.000Z"
      }
    ]
  },
  "meta": { "request_id": "req_insights_ov_03", "timestamp": "2026-09-09T12:00:13.000Z" }
}

Slice the same window by feature/channel with GET /api/v1/insights/llm-spend/by-feature — it also returns your budget config and any per-channel threshold breaches in the same envelope:

curl -G "https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-feature" \
  -H "X-API-Key: dv_test_sk_your_test_key_here"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-feature",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const body = await res.json();
console.log(body.data.features.map((f) => `${f.channel}: ${f.total_cost_cents}`));

200

{
  "data": {
    "from": "2026-08-10T00:00:00.000Z",
    "to": "2026-09-09T00:00:00.000Z",
    "currency": "USD",
    "timezone": "America/New_York",
    "total_cents": 81200,
    "budget": {
      "monthly_cap_cents": 250000,
      "daily_cap_cents": 50000,
      "channel_thresholds": { "voice": 90000 }
    },
    "features": [
      { "channel": "voice", "total_cost_cents": 42300, "total_tokens": 1900000, "event_count": 1870 },
      { "channel": "sms", "total_cost_cents": 38900, "total_tokens": 2220000, "event_count": 2310 }
    ],
    "threshold_breaches": []
  },
  "meta": { "request_id": "req_insights_ov_04", "timestamp": "2026-09-09T12:00:14.000Z" }
}

8. Compare agents and isolate a quality gap by language

The comparison chain answers “which of my agents is the better value?” — GET /api/v1/insights/agent-comparison ranks two or more agents side by side against the org average on cost, attributed revenue, margin, containment, resolution, and escalation. Pass agentIds as a comma- separated list of at least two agents.

curl -G "https://api.orbit.devotel.io/api/v1/insights/agent-comparison" \
  -H "X-API-Key: dv_test_sk_your_test_key_here" \
  --data-urlencode "agentIds=ag_sales_assist,ag_support_front"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/agent-comparison",
);
url.searchParams.set("agentIds", "ag_sales_assist,ag_support_front");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
console.log(body.data.agents.map((a) => `${a.agent_name}: margin ${a.margin_percent}%`));

200

{
  "data": {
    "from": "2026-08-10T00:00:00.000Z",
    "to": "2026-09-09T00:00:00.000Z",
    "currency": "USD",
    "timezone": "America/New_York",
    "metrics": [
      { "key": "cost_cents", "label": "Cost", "unit": "cents", "higherIsBetter": false },
      { "key": "containment_rate", "label": "Containment %", "unit": "percent", "higherIsBetter": true }
    ],
    "population_size": 6,
    "ranked_population_size": 6,
    "population_truncated": false,
    "org_average": { "margin_percent": 41.2, "containment_rate": 68.9 },
    "agents": [
      {
        "agent_id": "ag_sales_assist",
        "agent_name": "Sales assist",
        "model": "acme/reasoning-large",
        "conversation_count": 1870,
        "cost_cents": 42300,
        "attributed_revenue_cents": 115200,
        "margin_cents": 72900,
        "margin_percent": 63.3,
        "containment_rate": 74.1,
        "resolution_rate": 81.2,
        "escalation_rate": 25.9
      },
      {
        "agent_id": "ag_support_front",
        "agent_name": "Support front line",
        "model": "acme/reasoning-small",
        "conversation_count": 2310,
        "cost_cents": 38900,
        "attributed_revenue_cents": 51100,
        "margin_cents": 12200,
        "margin_percent": 23.9,
        "containment_rate": 66.4,
        "resolution_rate": 77.8,
        "escalation_rate": 33.6
      }
    ]
  },
  "meta": { "request_id": "req_insights_cmp_01", "timestamp": "2026-09-09T12:00:15.000Z" }
}

When the comparison shows a quality gap, drill per locale with GET /api/v1/insights/agent-quality/by-language (rubric eval pass-rate, containment, sentiment, CSAT per detected language) — or with the window-level GET /api/v1/insights/language-quality when you want the same segmentation without the per-agent filter (chain 3 named it; the worked envelope here applies to both):

curl -G "https://api.orbit.devotel.io/api/v1/insights/agent-quality/by-language" \
  -H "X-API-Key: dv_test_sk_your_test_key_here"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/insights/agent-quality/by-language",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const body = await res.json();
console.log(body.data.languages.map((l) => `${l.language}: containment ${l.containment_rate}%`));

200

{
  "data": {
    "from": "2026-08-10T00:00:00.000Z",
    "to": "2026-09-09T00:00:00.000Z",
    "timezone": "America/New_York",
    "scanned_conversations": 4180,
    "scan_truncated": false,
    "totals": {
      "total_conversations": 4180,
      "containment_rate": 71.4,
      "resolution_rate": 80.3,
      "escalation_rate": 28.6,
      "avg_sentiment": 0.42,
      "avg_csat": 4.3,
      "language_count": 4
    },
    "languages": [
      {
        "language": "en",
        "language_name": "English",
        "total_conversations": 3120,
        "handed_off_count": 690,
        "contained_count": 2430,
        "resolved_count": 2510,
        "containment_rate": 77.9,
        "escalation_rate": 22.1,
        "resolution_rate": 80.4,
        "avg_sentiment": 0.48,
        "sentiment_sample": 2900,
        "avg_csat": 4.5,
        "csat_sample": 1800
      },
      {
        "language": "es",
        "language_name": "Spanish",
        "total_conversations": 640,
        "handed_off_count": 260,
        "contained_count": 380,
        "resolved_count": 470,
        "containment_rate": 59.4,
        "escalation_rate": 40.6,
        "resolution_rate": 73.4,
        "avg_sentiment": 0.31,
        "sentiment_sample": 600,
        "avg_csat": 4.0,
        "csat_sample": 410
      }
    ]
  },
  "meta": { "request_id": "req_insights_cmp_02", "timestamp": "2026-09-09T12:00:16.000Z" }
}

9. Read the spend caps before you raise them

The config reads answer “what caps are in force?” — GET /api/v1/insights/ llm-spend/budget returns the persisted budget blob (monthly/daily caps, per-channel thresholds, the soft-alert percentage, and the automatic model downshift toggle), GET /api/v1/insights/llm-spend/model-caps returns the per-model spend caps, and GET /api/v1/insights/agent-roi/config / GET /api/v1/insights/conversation-pnl/config / GET /api/v1/insights/cost-economics/config return the per-surface config the PUT endpoints on this page write. Read the config before you compose a PUT body — every PUT on this page is a read-merge-write against its GET envelope.

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

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/insights/llm-spend/budget",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const body = await res.json();
console.log(body.data.monthly_cap_cents, body.data.downshift.enabled);

200

{
  "data": {
    "monthly_cap_cents": 250000,
    "daily_cap_cents": 50000,
    "asr_monthly_cap_cents": null,
    "channel_thresholds": { "voice": 90000 },
    "alert_at_percent": 80,
    "downshift": {
      "enabled": true,
      "trigger_percent": 100,
      "model": "acme/reasoning-small"
    }
  },
  "meta": { "request_id": "req_insights_cfg_01", "timestamp": "2026-09-09T12:00:17.000Z" }
}

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/model-caps" \
  -H "X-API-Key: dv_test_sk_your_test_key_here"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/insights/llm-spend/model-caps",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const body = await res.json();
console.log(body.data.model_caps_cents);

200

{
  "data": {
    "model_caps_cents": {
      "acme/reasoning-large": 50000,
      "acme/reasoning-small": 20000
    }
  },
  "meta": { "request_id": "req_insights_cfg_02", "timestamp": "2026-09-09T12:00:18.000Z" }
}

10. Cost to serve: conversation P&L

GET /api/v1/insights/conversation-pnl blends telco, LLM, and human-agent labour into one cost-to-serve per conversation, per resolution, and per conversion — answer “what does a conversation actually cost me to run?” with a blended number, not a channel invoice. The labour rate comes from GET /api/v1/insights/conversation-pnl/config (the PUT on this page sets it), and the unit economics divide the SAME blended total by each volume denominator.

curl -G "https://api.orbit.devotel.io/api/v1/insights/conversation-pnl" \
  -H "X-API-Key: dv_test_sk_your_test_key_here"

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

200

{
  "data": {
    "from": "2026-08-10T00:00:00.000Z",
    "to": "2026-09-09T00:00:00.000Z",
    "currency": "USD",
    "timezone": "America/New_York",
    "config": { "human_agent_cost_per_hour_cents": 1800 },
    "applied_human_agent_cost_per_hour_cents": 1800,
    "costs": {
      "telco_cents": 31200,
      "telco_breakdown": { "voice_cents": 24800, "sms_cents": 5900, "mms_cents": 500 },
      "llm_cents": 81200,
      "human_agent_cents": 14600,
      "total_cents": 127000
    },
    "volume": {
      "conversation_count": 11148,
      "resolved_conversation_count": 8950,
      "conversion_count": 1210,
      "human_agent_seconds": 29200
    },
    "unit_economics": {
      "cost_per_conversation_cents": 11.4,
      "cost_per_resolution_cents": 14.2,
      "cost_per_conversion_cents": 104.9
    }
  },
  "meta": { "request_id": "req_insights_pnl_01", "timestamp": "2026-09-09T12:00:19.000Z" }
}

11. Platform-side economics to pair with spend

GET /api/v1/insights/cost-economics returns the platform cost side (provider telephony + inference per conversation) in the same window, so a margin report pairs the revenue surfaces (chains 4 and 10) against what the traffic costs the platform. Rate overwrites live under GET/PUT /api/v1/insights/cost-economics/config.

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

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/insights/cost-economics",
);
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.avg_cost_per_conversation_cents);

200

{
  "data": {
    "avg_cost_per_conversation_cents": 3.7,
    "window_days": 30,
    "conversation_count": 11148
  },
  "meta": { "request_id": "req_insights_pnl_02", "timestamp": "2026-09-09T12:00:20.000Z" }
}

Pagination and envelope rules

Config writes echo the config. PUT on a */config route (and on the LLM-spend budget / model-caps routes) returns the new config object in the same shape GET reports, not an empty body — data.human_agent_cost_per_hour_cents, data.model_caps_cents, or the full data.config block. Some OpenAPI documenters show a 202 for an accepted PATCH/PUT with no payload; chain on data from the response shown on this page, which the generator fills from the route’s actual controller echo even when the spec carries only 2xx.
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.

Error shapes: scope gap vs parameter issue

Failures come back in the { error, meta } envelope — branch on error.code, and quote meta.request_id when you escalate. Two non-success shapes recur across every Insights operation:

403

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient role for this operation",
    "status": 403
  },
  "meta": { "request_id": "req_insights_err_01", "timestamp": "2026-09-09T12:00:21.000Z" }
}

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameters",
    "status": 422,
    "details": {
      "issues": [
        { "field": "from", "message": "Expected ISO 8601 datetime" }
      ]
    }
  },
  "meta": { "request_id": "req_insights_err_02", "timestamp": "2026-09-09T12:00:22.000Z" }
}

Status	Code	What it means	What to do
403	`FORBIDDEN`	The key or role authenticated, but the Insights surface is gated by scope/role — the write (PUT) operations are owner/admin-only and several reads restrict to specific roles.	Surface it, don’t retry. Fix the key’s scopes on the developer page (or the caller’s role) — a retry with the same credential never heals a scope gap.
422	`VALIDATION_ERROR`	A query parameter or PUT body did not match the schema — `error.details.issues[]` names the offending `field` and a readable `message`.	Fix the request, then resend. Branch on `error.details.issues[].field`; a blind retry repeats the same 422. Two examples this page guards: `from`/`to` must be ISO-8601 datetimes inside a ≤365-day window, and `groupBy` on summary must be one of `agent	model	conversation`.

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.

Benchmark agents against the org population

GET /api/v1/insights/agent-benchmarks

Returns per-metric percentile, rank, and performance band for each AI agent versus the organisation’s agent population (cost, attributed revenue, margin, containment, resolution, escalation). The window defaults to the last 30 days (from/to, max 365 days); pass agentIds to restrict the comparison population.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests — see Test mode explained for the full credential-header matrix and worked samples. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/agent-benchmarks', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/agent-benchmarks", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "currency": "USD",
    "timezone": "UTC",
    "metrics": [
      {
        "key": "containment_rate",
        "label": "Containment rate",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "resolution_rate",
        "label": "Resolution rate",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "cost_cents",
        "label": "Cost",
        "unit": "cents",
        "higherIsBetter": false
      },
      {
        "key": "margin_percent",
        "label": "Margin",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "attributed_revenue_cents",
        "label": "Attributed revenue",
        "unit": "cents",
        "higherIsBetter": true
      },
      {
        "key": "margin_cents",
        "label": "Margin absolute",
        "unit": "cents",
        "higherIsBetter": true
      },
      {
        "key": "escalation_rate",
        "label": "Escalation rate",
        "unit": "percent",
        "higherIsBetter": false
      }
    ],
    "population_size": 4,
    "ranked_population_size": 4,
    "population_truncated": false,
    "org_average": {
      "cost_cents": 10421,
      "attributed_revenue_cents": 214500,
      "margin_cents": 204079,
      "margin_percent": 95.1,
      "containment_rate": 74.3,
      "resolution_rate": 69.8,
      "escalation_rate": 25.7
    },
    "agents": [
      {
        "agent_id": "agt_01JAQ2K8PF4X",
        "agent_name": "Support Intake",
        "model": "gpt-5-thinking",
        "conversation_count": 1284,
        "benchmarks": {
          "cost_cents": {
            "value": 10421,
            "org_average": 10421,
            "percentile": 62.1,
            "rank": 2,
            "sample_size": 4,
            "band": "above_average"
          },
          "attributed_revenue_cents": {
            "value": 214500,
            "org_average": 214500,
            "percentile": 88.4,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "margin_cents": {
            "value": 204079,
            "org_average": 204079,
            "percentile": 88.4,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "margin_percent": {
            "value": 95.1,
            "org_average": 95.1,
            "percentile": 75.2,
            "rank": 2,
            "sample_size": 4,
            "band": "above_average"
          },
          "containment_rate": {
            "value": 74.3,
            "org_average": 74.3,
            "percentile": 88.4,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "resolution_rate": {
            "value": 69.8,
            "org_average": 69.8,
            "percentile": 81.7,
            "rank": 1,
            "sample_size": 4,
            "band": "top_quartile"
          },
          "escalation_rate": {
            "value": 25.7,
            "org_average": 25.7,
            "percentile": 18.9,
            "rank": 4,
            "sample_size": 4,
            "band": "bottom_quartile"
          }
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Compare AI agents side by side

GET /api/v1/insights/agent-comparison

Ranks two or more AI agents against each other and the organisation average on the KPIs already computed per agent (cost, attributed revenue, margin, containment, resolution, escalation). Pass agentIds as a comma-separated list of at least two agents; the window defaults to the last 30 days and from/to accept ISO 8601 datetimes bounded to 365 days.

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/agent-comparison', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/agent-comparison", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "currency": "USD",
    "timezone": "UTC",
    "metrics": [
      {
        "key": "containment_rate",
        "label": "Containment rate",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "resolution_rate",
        "label": "Resolution rate",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "cost_cents",
        "label": "Cost",
        "unit": "cents",
        "higherIsBetter": false
      },
      {
        "key": "margin_percent",
        "label": "Margin",
        "unit": "percent",
        "higherIsBetter": true
      },
      {
        "key": "attributed_revenue_cents",
        "label": "Attributed revenue",
        "unit": "cents",
        "higherIsBetter": true
      },
      {
        "key": "margin_cents",
        "label": "Margin absolute",
        "unit": "cents",
        "higherIsBetter": true
      },
      {
        "key": "escalation_rate",
        "label": "Escalation rate",
        "unit": "percent",
        "higherIsBetter": false
      }
    ],
    "population_size": 4,
    "ranked_population_size": 4,
    "population_truncated": false,
    "org_average": {
      "cost_cents": 10421,
      "attributed_revenue_cents": 214500,
      "margin_cents": 204079,
      "margin_percent": 95.1,
      "containment_rate": 74.3,
      "resolution_rate": 69.8,
      "escalation_rate": 25.7
    },
    "agents": [
      {
        "agent_id": "agt_01JAQ2K8PF4X",
        "agent_name": "Support Intake",
        "model": "gpt-5-thinking",
        "conversation_count": 1284,
        "cost_cents": 10421,
        "attributed_revenue_cents": 214500,
        "margin_cents": 204079,
        "margin_percent": 95.1,
        "containment_rate": 74.3,
        "resolution_rate": 69.8,
        "escalation_rate": 25.7
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Agent quality segmented by detected language

GET /api/v1/insights/agent-quality/by-language

Segments the AI-agent quality signals (containment, resolution, rubric eval pass-rate, CSAT, sentiment) by the conversation’s detected language, so a multilingual team can spot the locale the bot handles worse than English. The window defaults to the last 30 days (from/to, max 365 days); limit bounds the displayed language rows (totals are always computed across the full set).

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/agent-quality/by-language" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/agent-quality/by-language', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/agent-quality/by-language", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "languages": [
      {
        "language": "en",
        "total_conversations": 1284,
        "handed_off_count": 291,
        "contained_count": 993,
        "resolved_count": 948,
        "containment_rate": 77.3,
        "escalation_rate": 22.7,
        "resolution_rate": 73.8,
        "csat_count": 412,
        "avg_csat": 4.32,
        "sentiment_count": 987,
        "positive_count": 688,
        "neutral_count": 184,
        "negative_count": 115,
        "avg_sentiment": 0.42,
        "net_sentiment": 58.1,
        "evaluated_count": 602,
        "eval_passed_count": 518,
        "eval_pass_rate": 86
      }
    ],
    "totals": {
      "language": null,
      "total_conversations": 1284,
      "handed_off_count": 291,
      "contained_count": 993,
      "resolved_count": 948,
      "containment_rate": 77.3,
      "escalation_rate": 22.7,
      "resolution_rate": 73.8,
      "csat_count": 412,
      "avg_csat": 4.32,
      "sentiment_count": 987,
      "positive_count": 688,
      "neutral_count": 184,
      "negative_count": 115,
      "avg_sentiment": 0.42,
      "net_sentiment": 58.1,
      "evaluated_count": 602,
      "eval_passed_count": 518,
      "eval_pass_rate": 86,
      "language_count": 3
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get per-agent ROI summary

GET /api/v1/insights/agent-roi

Joins LLM cost and outcome-evaluation data into a per-agent return-on-investment table: cost, attributed revenue (from configurable per-outcome values), and margin. All money fields are integer cents. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days); limit caps the agent rows (≤200).

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/agent-roi', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/agent-roi", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "currency": "USD",
    "timezone": "UTC",
    "config": {
      "default_outcome_value_cents": 20000,
      "per_rubric_value_cents": {
        "rub_01JBX8ZK2Q": 45000
      }
    },
    "totals": {
      "cost_cents": 10421,
      "attributed_revenue_cents": 214500,
      "margin_cents": 204079,
      "margin_percent": 95.1,
      "outcomes_count": 12,
      "conversation_count": 1284,
      "agent_count": 4,
      "shown_count": 4,
      "truncated": false
    },
    "agents": [
      {
        "agent_id": "agt_01JAQ2K8PF4X",
        "agent_name": "Support Intake",
        "model": "gpt-5-thinking",
        "cost_cents": 10421,
        "attributed_revenue_cents": 214500,
        "margin_cents": 204079,
        "margin_percent": 95.1,
        "outcomes_count": 12,
        "conversation_count": 1284,
        "outcomes": [
          {
            "rubric_id": "rub_01JBX8ZK2Q",
            "rubric_name": "Lead qualified",
            "passed_count": 12,
            "value_cents": 45000,
            "subtotal_cents": 540000
          }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get ROI attribution configuration

GET /api/v1/insights/agent-roi/config

Returns the outcome-value attribution configuration the per-agent ROI table is computed with: the default value of one resolved conversation and any per-rubric overrides (integer cents). Workspaces that never configured these see the defaults (null default, empty overrides), so a settings form always renders a stable shape.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/agent-roi/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/agent-roi/config', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/agent-roi/config", headers=headers)
print(r.json())

{
  "data": {
    "default_outcome_value_cents": 20000,
    "per_rubric_value_cents": {
      "rub_01JBX8ZK2Q": 45000
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get the daily ROI trend

GET /api/v1/insights/agent-roi/timeseries

Returns the daily cost, attributed revenue, and margin trend (integer cents) for the ROI dashboard chart. Defaults to the last 30 days (from/to ISO datetimes, max 365 days); pass agentId to scope the trend to one agent instead of the org-wide aggregate.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/agent-roi/timeseries" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/agent-roi/timeseries', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/agent-roi/timeseries", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "granularity": "day",
    "currency": "USD",
    "timezone": "UTC",
    "agent_id": null,
    "series": [
      {
        "bucket": "2026-09-21",
        "cost_cents": 374,
        "attributed_revenue_cents": 8200,
        "margin_cents": 7826,
        "margin_percent": 95.4
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Aggregate anomaly ledger by scope

GET /api/v1/insights/anomaly-insights/by-scope

Rolls the spend-forensics anomaly ledger (wallet-burn and webhook anomalies) up per scope group — wallet, webhook, and all-total — with open and severity counts. Filter with ?scope=wallet|webhook; the window defaults to the last 30 days (days, or from/to ISO datetimes, up to 365 days).

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/by-scope" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/by-scope', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/by-scope", headers=headers)
print(r.json())

{
  "data": {
    "window": {
      "from": "2026-08-31T00:00:00.000Z",
      "to": "2026-09-29T00:00:00.000Z",
      "days": 30
    },
    "scopes": [
      {
        "scope": "wallet",
        "total": 6,
        "open_count": 5,
        "high_or_critical_count": 3,
        "latest_detected_at": "2026-09-28T08:15:00.000Z"
      },
      {
        "scope": "webhook",
        "total": 2,
        "open_count": 1,
        "high_or_critical_count": 1,
        "latest_detected_at": "2026-09-27T02:41:00.000Z"
      },
      8
    ],
    "all_total": 8,
    "truncated": null
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

List anomaly ledger items

GET /api/v1/insights/anomaly-insights/history

Returns the individual spend-forensics anomaly items (category, severity, status, summary, detection time) for the forensic drill-down table, newest first. Filter with ?scope=wallet|webhook and page with ?limit (≤100 per page); the window defaults to the last 30 days (days, or from/to ISO datetimes, up to 365 days).

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/history', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/history", headers=headers)
print(r.json())

{
  "data": {
    "window": {
      "from": "2026-08-31T00:00:00.000Z",
      "to": "2026-09-29T00:00:00.000Z",
      "days": 30
    },
    "scope": "all",
    "items": [
      {
        "id": "anm_01JC9PX7K2",
        "category": "spend_spike",
        "severity": "high",
        "status": "open",
        "scope": "wallet",
        "source": "burn-rate",
        "summary": "Daily LLM spend exceeded the configured cap by 312%.",
        "channel": "sms",
        "detected_at": "2026-09-28T08:15:00.000Z",
        "triaged_at": null,
        "resolved_at": null,
        "details": {
          "cap_cents": 50000,
          "observed_cents": 156020
        }
      }
    ],
    "total": 8
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Anomaly counts over time

GET /api/v1/insights/anomaly-insights/timeseries

Buckets the spend-forensics anomaly ledger into a zero-filled per-day histogram (one count per UTC day per requested scope) for the dashboard trendline. Filter with ?scope=wallet|webhook; the window defaults to the last 30 days (days, or from/to ISO datetimes, up to 365 days).

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/timeseries', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/anomaly-insights/timeseries", headers=headers)
print(r.json())

{
  "data": {
    "window": {
      "from": "2026-08-31T00:00:00.000Z",
      "to": "2026-09-29T00:00:00.000Z",
      "days": 30
    },
    "scope": "all",
    "buckets": [
      {
        "day": "2026-09-27",
        "scope": "wallet",
        "total": 1
      },
      {
        "day": "2026-09-27",
        "scope": "webhook",
        "total": 1
      },
      {
        "day": "2026-09-28",
        "scope": "wallet",
        "total": 5
      }
    ],
    "truncated": null
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

List ranked automation opportunities

GET /api/v1/insights/automation-opportunities

Mines the organisation’s cross-channel conversation corpus and ranks the contact reasons worth automating next — each with a projected deflection volume, projected monthly savings (integer cents), and a scaffold suggestion ready for a one-click build. Tune the ROI assumptions via /automation-opportunities/config. The window defaults to the last 30 days (from/to, max 365 days); limit caps the returned opportunity count.

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/automation-opportunities', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/automation-opportunities", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-08-31T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "window_days": 30,
    "currency": "USD",
    "config": {
      "agent_cost_per_hour_cents": 9000,
      "automation_cost_per_contact_cents": 37,
      "target_deflection_rate": 0.6,
      "default_aht_seconds": 420,
      "min_volume": 50
    },
    "totals": {
      "opportunity_count": 3,
      "shown_count": 3,
      "truncated": false,
      "total_automatable_volume": 412,
      "total_projected_monthly_deflections": 412,
      "total_projected_monthly_savings_cents": 28840
    },
    "opportunities": [
      {
        "topic": "refunds",
        "volume": 128,
        "previous_volume": 94,
        "trend": "rising",
        "change_pct": 36.2,
        "channels": {
          "whatsapp": 128,
          "sms": 0
        },
        "primary_channel": "whatsapp",
        "current_deflection_rate": 0.11,
        "avg_aht_seconds": 381,
        "target_deflection_rate": 0.6,
        "automatable_volume": 76,
        "projected_monthly_deflections": 76,
        "handle_cost_per_contact_cents": 525,
        "automation_cost_per_contact_cents": 37,
        "net_savings_per_deflection_cents": 488,
        "projected_monthly_savings_cents": 37088,
        "opportunity_score": 92.4,
        "scaffold": {
          "kind": "flow",
          "title": "Automate refund status checks",
          "description": "Route refund questions into a flow that looks up the order and replies with the refund state.",
          "primary_channel": "whatsapp",
          "source_topic": "refund status"
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get automation ROI assumptions

GET /api/v1/insights/automation-opportunities/config

Returns the ROI assumptions the Automation Opportunity Miner uses to project savings: human agent cost per hour, automation cost per contact, target deflection rate, default handle time, and the minimum monthly volume a reason needs to qualify. Workspaces that never configured these see the defaults, so the settings form always renders a stable shape.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/automation-opportunities/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/automation-opportunities/config', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/automation-opportunities/config", headers=headers)
print(r.json())

{
  "data": {
    "agent_cost_per_hour_cents": 9000,
    "automation_cost_per_contact_cents": 37,
    "target_deflection_rate": 0.6,
    "default_aht_seconds": 420,
    "min_volume": 50
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get inbound-call marketing attribution

GET /api/v1/insights/call-attribution

Rolls inbound calls, answer rate, and duration up by marketing source by joining the organisation’s call-tracking pools to inbound call logs at read time — the CallRail/Invoca-style ‘which campaign drove this call’ report. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days).

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/call-attribution', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/call-attribution", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "totals": {
      "calls": 412,
      "answered": 301,
      "missed": 111,
      "answer_rate": 73.1,
      "total_duration_seconds": 81200,
      "avg_duration_seconds": 197,
      "unique_callers": 356,
      "source_count": 2,
      "tracked_number_count": 3
    },
    "sources": [
      {
        "source": "paid-search",
        "campaign": "q3_intent",
        "medium": "cpc",
        "pools": [
          "pool_01JB2Y4"
        ],
        "tracked_numbers": 2,
        "calls": 238,
        "answered": 184,
        "missed": 54,
        "answer_rate": 77.3,
        "total_duration_seconds": 51200,
        "avg_duration_seconds": 215,
        "unique_callers": 204
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get AI-agent containment summary

GET /api/v1/insights/containment

Reports the share of AI-agent conversations the bot handled without a human handoff (containment) and the share that reached a resolved status or passed a rubric outcome (resolution), per agent and org-wide. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days); limit caps the agent rows (≤200).

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/containment', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/containment", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "timezone": "UTC",
    "totals": {
      "total_conversations": 1284,
      "handed_off_count": 291,
      "contained_count": 993,
      "resolved_count": 948,
      "containment_rate": 77.3,
      "escalation_rate": 22.7,
      "resolution_rate": 73.8,
      "agent_count": 4
    },
    "agents": [
      {
        "agent_id": "agt_01JAQ2K8PF4X",
        "agent_name": "Support Intake",
        "model": "gpt-5-thinking",
        "total_conversations": 1284,
        "handed_off_count": 291,
        "contained_count": 993,
        "resolved_count": 948,
        "containment_rate": 77.3,
        "resolution_rate": 73.8
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get the daily containment trend

GET /api/v1/insights/containment/timeseries

Returns the daily containment and resolution trend for the dashboard chart. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days); pass agentId to scope the trend to one agent instead of the org-wide aggregate.

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/containment/timeseries', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/containment/timeseries", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "granularity": "day",
    "timezone": "UTC",
    "agent_id": null,
    "series": [
      {
        "bucket": "2026-09-21",
        "total_conversations": 96,
        "handed_off_count": 21,
        "contained_count": 75,
        "resolved_count": 71,
        "containment_rate": 78.1,
        "resolution_rate": 74
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get blended cost-to-serve summary

GET /api/v1/insights/conversation-pnl

Joins telco spend (call/message price), AI-agent LLM spend, and human-agent handle time priced at a configurable hourly rate into one cost-to-serve figure, then divides by conversations, resolutions, and conversions. All money fields are integer cents. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days).

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/conversation-pnl', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/conversation-pnl", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "currency": "USD",
    "timezone": "UTC",
    "config": {
      "human_agent_cost_per_hour_cents": 9000
    },
    "applied_human_agent_cost_per_hour_cents": 9000,
    "costs": {
      "telco_cents": 18420,
      "telco_breakdown": {
        "voice_cents": 12100,
        "sms_cents": 5820,
        "mms_cents": 500
      },
      "llm_cents": 3194,
      "human_agent_cents": 19042,
      "total_cents": 40656
    },
    "volume": {
      "conversation_count": 1284,
      "resolved_conversation_count": 948,
      "conversion_count": 312,
      "human_agent_seconds": 76178
    },
    "unit_economics": {
      "cost_per_conversation_cents": 32,
      "cost_per_resolution_cents": 43,
      "cost_per_conversion_cents": 130
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get P&L labour-rate configuration

GET /api/v1/insights/conversation-pnl/config

Returns the human-agent hourly rate (integer cents) used to price handle time in the cost-to-serve roll-up. Workspaces that never configured a rate see null, meaning the platform default applies, so the settings form always renders a stable shape.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/conversation-pnl/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/conversation-pnl/config', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/conversation-pnl/config", headers=headers)
print(r.json())

{
  "data": {
    "human_agent_cost_per_hour_cents": 9000
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get cross-channel unit economics

GET /api/v1/insights/cost-economics

Rolls per-message (SMS/WhatsApp), per-minute (voice/video), and per-1k-token (AI) usage into one margin and unit-economics view across the organisation’s channels. Money is integer cents; per-unit ratios read null when the channel’s volume is zero. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days).

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/cost-economics', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/cost-economics", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "currency": "USD",
    "timezone": "UTC",
    "config": {
      "sms_per_message_cents": 0.7,
      "whatsapp_per_message_cents": 0.3,
      "voice_per_minute_cents": 0.7,
      "ai_per_1000_tokens_cents": 0.2,
      "video_per_minute_cents": 0.8
    },
    "applied": {
      "sms_per_message_cents": 0.7,
      "whatsapp_per_message_cents": 0.3,
      "voice_per_minute_cents": 0.7,
      "ai_per_1000_tokens_cents": 0.2,
      "video_per_minute_cents": 0.8
    },
    "channels": [
      {
        "channel": "sms",
        "volume": 12800,
        "cost_cents": 8960,
        "per_unit_cost_cents": 0.7
      }
    ],
    "totals": {
      "cost_cents": 18420,
      "message_volume": 12800,
      "voice_minutes": 412,
      "ai_tokens": 1840000
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get cost-economics rate configuration

GET /api/v1/insights/cost-economics/config

Returns the per-unit rate overrides configured for the cost-economics view — SMS/WhatsApp per message, voice/video per minute, AI per 1,000 tokens (all integer cents, each nullable). Fields the workspace never set come back null, meaning the platform reference rate applies.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/cost-economics/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/cost-economics/config', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/cost-economics/config", headers=headers)
print(r.json())

{
  "data": {
    "sms_per_message_cents": 0.7,
    "whatsapp_per_message_cents": 0.3,
    "voice_per_minute_cents": 0.7,
    "ai_per_1000_tokens_cents": 0.2,
    "video_per_minute_cents": 0.8
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get KB auto-draft configuration

GET /api/v1/insights/kb-auto-draft/config

Returns the closed-loop knowledge-base auto-draft settings: whether the miner is enabled and the maximum drafts filed per run. Workspaces that never opted in see the defaults, so the settings form always renders a stable shape.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/config', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/config", headers=headers)
print(r.json())

{
  "data": {
    "enabled": true,
    "max_drafts_per_run": 5
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get language-segmented quality summary

GET /api/v1/insights/language-quality

Segments the containment, resolution/escalation, sentiment, and CSAT quality signals by the conversation’s detected language so a multilingual team can find the locale the bot handles worse than another. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days).

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/language-quality', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/language-quality", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "timezone": "UTC",
    "scanned_conversations": 1284,
    "scan_truncated": false,
    "totals": {
      "total_conversations": 1284,
      "handed_off_count": 291,
      "contained_count": 993,
      "resolved_count": 948,
      "containment_rate": 77.3,
      "escalation_rate": 22.7,
      "resolution_rate": 73.8,
      "avg_sentiment": 0.42,
      "avg_csat": 4.32,
      "language_count": 3
    },
    "languages": [
      {
        "language": "en",
        "language_name": "English",
        "total_conversations": 1284,
        "handed_off_count": 291,
        "contained_count": 993,
        "resolved_count": 948,
        "containment_rate": 77.3,
        "escalation_rate": 22.7,
        "resolution_rate": 73.8,
        "avg_sentiment": 0.42,
        "sentiment_sample": 987,
        "avg_csat": 4.32,
        "csat_sample": 412
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get AI budget configuration

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

Returns the workspace’s AI-spend guardrails — monthly and daily caps (integer cents, nullable), the alert threshold percentage, per-channel thresholds, and the configured automatic model-downshift policy. Workspaces that never set a config see their stored defaults, so the settings form always renders a stable shape.

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/budget', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

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

{
  "data": {
    "monthly_cap_cents": 500000,
    "daily_cap_cents": 50000,
    "asr_monthly_cap_cents": null,
    "channel_thresholds": {
      "sms": 100000,
      "whatsapp": 100000
    },
    "alert_at_percent": 80,
    "downshift": {
      "enabled": true,
      "trigger_percent": 90,
      "model": "gpt-5-mini"
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get AI spend by feature

GET /api/v1/insights/llm-spend/by-feature

Aggregates AI spend per feature channel (calls, messaging, agents, and other AI surfaces) so operators can see which product area is driving cost, alongside the org’s budget config and any threshold breaches — the whole panel in one roundtrip. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days).

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-feature" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-feature', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

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

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "currency": "USD",
    "timezone": "UTC",
    "total_cents": 41250,
    "budget": {
      "monthly_cap_cents": 500000,
      "daily_cap_cents": 50000,
      "asr_monthly_cap_cents": null,
      "channel_thresholds": {
        "sms": 100000,
        "whatsapp": 100000
      },
      "alert_at_percent": 80,
      "downshift": {
        "enabled": true,
        "trigger_percent": 90,
        "model": "gpt-5-mini"
      }
    },
    "features": [
      {
        "channel": "agents",
        "total_cost_cents": 41250,
        "total_tokens": 1840000,
        "event_count": 1284
      }
    ],
    "threshold_breaches": [
      {
        "channel": "sms",
        "cents": 123400,
        "threshold_cents": 100000,
        "percent": 123.4
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get AI spend by model

GET /api/v1/insights/llm-spend/by-model

Aggregates AI spend per model with what each model costs Devotel (COGS) versus what the workspace is billed, exposing per-model margin, alongside the org’s per-model cap config and any cap breaches — the whole panel in one roundtrip. All money fields are integer cents. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days).

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-model" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/by-model', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

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

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "currency": "USD",
    "total_billed_cents": 41250,
    "total_cogs_cents": 27100,
    "total_margin_cents": 14150,
    "caps": {
      "model_caps_cents": {
        "gpt-5-thinking": 50000,
        "gpt-5-mini": 5000
      }
    },
    "models": [
      {
        "model": "gpt-5-thinking",
        "billed_cents": 41250,
        "cogs_cents": 27100,
        "margin_cents": 14150,
        "margin_bps": 3430,
        "total_tokens": 1840000,
        "event_count": 1284
      }
    ],
    "cap_breaches": [
      {
        "model": "gpt-5-thinking",
        "cents": 61200,
        "cap_cents": 50000,
        "percent": 122.4
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get per-model spend caps

GET /api/v1/insights/llm-spend/model-caps

Returns the per-model AI-spend cap map (model id → integer cents). A workspace that never set model-level caps gets an empty map, so the settings form always renders a stable shape.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/model-caps" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/model-caps', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

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

{
  "data": {
    "model_caps_cents": {
      "gpt-5-thinking": 50000,
      "gpt-5-mini": 5000
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get AI-spend headline stats

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

Returns the LLM-spend dashboard header — total spend, per-day trend, and the configured daily/monthly cap so the panel can render the cap-progress ring and percentage-used badge. All money fields are integer cents.

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/overview', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

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

{
  "data": {
    "currency": "USD",
    "timezone": "UTC",
    "daily_cap_cents": 50000,
    "today": {
      "spend_cents": 6220,
      "cap_percentage": 12.4
    },
    "month_to_date": {
      "spend_cents": 41250,
      "projected_month_end_cents": 88900,
      "vs_last_period_percent": -18.2,
      "days_remaining_in_month": 2
    },
    "last_7d_spend_cents": 91300
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get grouped AI-spend summary

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

Aggregates AI spend over a window grouped by agent, model, or conversation. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days); groupBy picks the grouping (default agent) and limit (≤200) caps the group rows. All money fields are integer cents.

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/summary', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

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

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "group_by": "agent",
    "currency": "USD",
    "timezone": "UTC",
    "totals": {
      "total_tokens": 1840000,
      "total_cost_cents": 41250,
      "conversation_count": 1284
    },
    "groups": [
      {
        "group_id": "agt_01JAQ2K8PF4X",
        "group_label": "Support Intake",
        "model": "gpt-5-thinking",
        "total_tokens": 1840000,
        "total_cost_cents": 41250,
        "conversation_count": 1284
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get AI-spend trend buckets

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

Returns AI spend bucketed for the dashboard chart. Hour-grain buckets are capped to a 14-day window; switch to granularity=day for longer ranges (max 365 days). The window defaults to 30 days at day-grain or 7 days at hour-grain. All money fields are integer cents.

string (enum: true|false)

cURL

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

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/timeseries', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

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

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "granularity": "day",
    "currency": "USD",
    "timezone": "UTC",
    "series": [
      {
        "bucket": "2026-09-28",
        "total_tokens": 61200,
        "total_cost_cents": 1404
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get top-spending conversations

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

Ranks the most expensive AI conversations over the window so operators can drill into outlier conversations driving the org’s AI spend. The window defaults to the last 30 days (from/to ISO datetimes, max 365 days); limit (≤50) caps the returned rows. All money fields are integer cents.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/llm-spend/top-conversations" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/top-conversations', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

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

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "currency": "USD",
    "timezone": "UTC",
    "conversations": [
      {
        "conversation_id": "cnv_01JC9QX4",
        "agent_id": "agt_01JAQ2K8PF4X",
        "agent_name": "Support Intake",
        "model": "gpt-5-thinking",
        "total_tokens": 128400,
        "total_cost_cents": 3180,
        "started_at": "2026-09-28T07:58:11.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get no-match miner configuration

GET /api/v1/insights/no-match-questions/config

Returns the no-match query miner’s per-workspace settings: whether the miner is enabled, the conversation volume a mapped reason must reach before it surfaces, the transcript count an unknown-topic cluster needs, and the maximum suggestions per run. Workspaces that never opted in see the defaults (enabled: false), so the settings form always renders a stable shape.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/no-match-questions/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/no-match-questions/config', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/no-match-questions/config", headers=headers)
print(r.json())

{
  "data": {
    "enabled": true,
    "min_volume": 10,
    "min_cluster_volume": 4,
    "max_suggestions": 25
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get sales conversation intelligence summary

GET /api/v1/insights/sales-conversation-intelligence

Rolls the post-call sales-intelligence analysis up across voice calls: average rep talk-ratio, the deal-risk band distribution, top competitor mentions, and the at-risk deal rollup per contact with the latest next steps. Tune the lookback with ?days (1–90, default 30). Configure the feature flag and competitor tracker terms via /sales-conversation-intelligence/config.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence", headers=headers)
print(r.json())

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-29T00:00:00.000Z",
    "calls_analyzed": 84,
    "avg_rep_talk_ratio": 0.42,
    "risk_band_distribution": {
      "low": 61,
      "medium": 17,
      "high": 6
    },
    "top_competitor_mentions": [
      {
        "term": "AcmeVoice",
        "count": 9
      }
    ],
    "at_risk_deals": [
      {
        "contact_id": "cnt_01JC2Z9X4T",
        "calls_count": 3,
        "avg_risk_score": 72,
        "latest_risk_band": "high",
        "latest_next_steps": [
          "Book a follow-up demo for the procurement team"
        ],
        "latest_analyzed_at": "2026-09-28T14:02:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Get sales intelligence configuration

GET /api/v1/insights/sales-conversation-intelligence/config

Returns the sales conversation intelligence settings: whether the per-call analyzer is enabled and the competitor tracker terms matched against call transcripts. Workspaces that never configured the feature see the defaults, so the settings form always renders a stable shape.

string (enum: true|false)

cURL

curl "https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence/config', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence/config", headers=headers)
print(r.json())

{
  "data": {
    "enabled": true,
    "competitor_trackers": [
      "AcmeVoice"
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Run the KB auto-draft miner

POST /api/v1/insights/kb-auto-draft/run

Triggers the knowledge-base auto-draft miner immediately (independent of the schedule). Draft articles are built from real mined conversation excerpts and filed as pending documents in the draft knowledge base awaiting human approval. Returns the run report. Requires the owner, admin, or developer role.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/run" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/run', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/run", headers=headers)
print(r.json())

{
  "data": {
    "ok": true,
    "kbId": "kb_01JC4RW2M8",
    "drafted": 3,
    "candidates": 17
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Run the no-match query miner

POST /api/v1/insights/no-match-questions/run

Triggers the no-match query miner for this workspace immediately (independent of the schedule). Mined coverage gaps become draft KB articles filed to the pending-approval pool plus exemplar-candidate and unknown-topic advisories; an explicit run counts as the opt-in consent the scheduled gate requires. Returns the run report. Requires the owner, admin, or developer role.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/insights/no-match-questions/run" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/no-match-questions/run', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/insights/no-match-questions/run", headers=headers)
print(r.json())

{
  "data": {
    "ok": true,
    "gaps": [
      {
        "kind": "draft_kb_article",
        "bucket": {
          "kind": "derives_reason",
          "signature": "refund_status",
          "volume": 12,
          "examples": [
            "where is my refund"
          ],
          "primary_channel": "whatsapp",
          "deflection_rate": 0.11
        },
        "title": "Refund status deep-dive",
        "description": "Write a KB article explaining refund statuses and expected timelines for this signature.",
        "draft_markdown": "# Refund status\nRefunds take 3-5 business days."
      }
    ],
    "drafts_filed": 3,
    "advisories": 12
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Update ROI attribution configuration

PUT /api/v1/insights/agent-roi/config

Replaces the outcome-value attribution configuration used by the per-agent ROI table. Fields are optional and merged with the current values (read-merge-write); pass default_outcome_value_cents: null to clear the default and per_rubric_value_cents as a rubric-id → integer-cents map (≤500 overrides). No money moves on this call — the values only change how outcome revenue is attributed. The updated, persisted configuration is returned.

string

string (enum: true|false)

integer

Default attributed value of one resolved outcome, in integer cents (null clears the default).

object

Per-rubric attributed values in integer cents, keyed by rubric id (at most 500 overrides).

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/insights/agent-roi/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/agent-roi/config', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.put("https://api.orbit.devotel.io/api/v1/insights/agent-roi/config", headers=headers)
print(r.json())

{
  "data": {
    "default_outcome_value_cents": 20000,
    "per_rubric_value_cents": {
      "rub_01JBX8ZK2Q": 45000
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Update automation ROI assumptions

PUT /api/v1/insights/automation-opportunities/config

Replaces the ROI assumptions the Automation Opportunity Miner uses to project savings. Send a partial body with at least one field; omitted fields keep their current values and the updated, persisted configuration is returned.

string

string (enum: true|false)

integer

Human agent cost per hour, integer cents.

integer

Automation cost per handled contact, integer cents.

number

Target deflection rate as a fraction between 0 and 1.

integer

Default average handle time in seconds used when no measured value exists.

integer

Minimum monthly contact volume a reason needs to qualify as an opportunity.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/insights/automation-opportunities/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/automation-opportunities/config', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.put("https://api.orbit.devotel.io/api/v1/insights/automation-opportunities/config", headers=headers)
print(r.json())

{
  "data": {
    "agent_cost_per_hour_cents": 9000,
    "automation_cost_per_contact_cents": 37,
    "target_deflection_rate": 0.6,
    "default_aht_seconds": 420,
    "min_volume": 50
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Update P&L labour-rate configuration

PUT /api/v1/insights/conversation-pnl/config

Replaces the human-agent hourly rate used to price handle time in the conversation P&L roll-up. Send a partial body; omitted fields keep their current values, and null clears the override back to the platform default. The updated, persisted configuration is returned.

string

string (enum: true|false)

integer

Hourly rate used to price human-agent handle time, in integer cents (null clears the override).

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/insights/conversation-pnl/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/conversation-pnl/config', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.put("https://api.orbit.devotel.io/api/v1/insights/conversation-pnl/config", headers=headers)
print(r.json())

{
  "data": {
    "human_agent_cost_per_hour_cents": 9000
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Update cost-economics rate configuration

PUT /api/v1/insights/cost-economics/config

Replaces the per-unit rate overrides used by the cost-economics view. Send a partial body; omitted fields keep their current values and any field set to null falls back to the platform reference rate. The updated, persisted configuration is returned.

string

string (enum: true|false)

integer

SMS cost per message, integer cents (null clears the override).

integer

WhatsApp cost per message, integer cents (null clears the override).

integer

Voice cost per minute, integer cents (null clears the override).

integer

AI cost per 1,000 tokens, integer cents (null clears the override).

integer

Video cost per minute, integer cents (null clears the override).

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/insights/cost-economics/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/cost-economics/config', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

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

{
  "data": {
    "sms_per_message_cents": 0.7,
    "whatsapp_per_message_cents": 0.3,
    "voice_per_minute_cents": 0.7,
    "ai_per_1000_tokens_cents": 0.2,
    "video_per_minute_cents": 0.8
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Update KB auto-draft configuration

PUT /api/v1/insights/kb-auto-draft/config

Replaces the knowledge-base auto-draft settings. Send a partial body with at least one field — enabled to toggle the miner, max_drafts_per_run to bound the drafts per run; omitted fields keep their current values and the updated, persisted configuration is returned.

string

string (enum: true|false)

boolean

Whether the auto-draft miner runs for this workspace.

integer

Maximum draft articles filed per run.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/config', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.put("https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/config", headers=headers)
print(r.json())

{
  "data": {
    "enabled": true,
    "max_drafts_per_run": 5
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Update AI budget configuration

PUT /api/v1/insights/llm-spend/budget

Replaces AI-spend guardrails: monthly/daily caps (integer cents, use null to remove a cap), alert threshold percentage, and the automatic model-downshift policy. Send a partial body; omitted fields keep their current values (read-merge-write). The updated, persisted configuration is returned.

string

string (enum: true|false)

integer

Monthly AI-spend cap in integer cents (null removes the cap).

integer

Daily AI-spend cap in integer cents (null removes the cap).

integer

Advisory monthly cap for speech-to-text spend, integer cents (null removes it).

object

Per-channel threshold map (channel name → integer cents).

integer

Percentage of cap at which an alert trips (1–100).

object

—

number

required

Hard daily spend ceiling in USD cents. Refuses LLM enqueue past the threshold; 200 = $2.00/day.

number

Optional monthly ceiling in USD cents (resets on the 1st). When omitted, only the daily cap applies.

number

Percent (10–99) at which a budget-exhausting advisory webhook fires before the hard cap.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/insights/llm-spend/budget" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "daily_budget_cents": 200,
  "monthly_budget_cents": 5000,
  "alert_threshold_pct": 80
}'

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/budget', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "daily_budget_cents": 200,
  "monthly_budget_cents": 5000,
  "alert_threshold_pct": 80
})
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.put("https://api.orbit.devotel.io/api/v1/insights/llm-spend/budget", headers=headers, json={
  "daily_budget_cents": 200,
  "monthly_budget_cents": 5000,
  "alert_threshold_pct": 80
})
print(r.json())

{
  "data": {
    "daily_budget_cents": 200,
    "monthly_budget_cents": 5000,
    "alert_threshold_pct": 80,
    "updated_at": "2026-08-26T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Update per-model spend caps

PUT /api/v1/insights/llm-spend/model-caps

Replaces the per-model AI-spend cap map. Send a partial body; when model_caps_cents is omitted the currently persisted caps are kept (read-merge-write). The updated, persisted configuration is returned.

string

string (enum: true|false)

object

Map of model id → cap in integer cents. Omitted keeps the current caps.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/insights/llm-spend/model-caps" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/llm-spend/model-caps', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.put("https://api.orbit.devotel.io/api/v1/insights/llm-spend/model-caps", headers=headers)
print(r.json())

{
  "data": {
    "model_caps_cents": {
      "gpt-5-thinking": 50000,
      "gpt-5-mini": 5000
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Update no-match miner configuration

PUT /api/v1/insights/no-match-questions/config

Replaces the no-match query miner’s settings. Send a partial body with at least one field — enabled toggles the scheduled miner, min_volume and min_cluster_volume set the floors a no-match reason or unknown-topic cluster must reach to surface, max_suggestions (≤50) bounds the results per run; omitted fields keep their current values and the updated, persisted configuration is returned.

string

string (enum: true|false)

boolean

Whether the no-match miner runs for this workspace (default false).

integer

Conversation volume a mapped reason must reach before it surfaces.

integer

Distinct transcripts an unknown-topic cluster needs before it surfaces.

integer

Maximum clusters and suggestions returned per run (≤50).

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/insights/no-match-questions/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/no-match-questions/config', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.put("https://api.orbit.devotel.io/api/v1/insights/no-match-questions/config", headers=headers)
print(r.json())

{
  "data": {
    "enabled": true,
    "min_volume": 10,
    "min_cluster_volume": 4,
    "max_suggestions": 25
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Update sales intelligence configuration

PUT /api/v1/insights/sales-conversation-intelligence/config

Replaces the sales conversation intelligence settings. Send a partial body with at least one field — enabled toggles the per-call analyzer, competitor_trackers is the list of competitor terms matched against transcripts (≤50 terms, ≤64 characters each); omitted fields keep their current values and the updated, persisted configuration is returned.

string

string (enum: true|false)

boolean

Whether the per-call sales-intelligence analyzer runs for this workspace.

string[]

Competitor tracker terms matched against call transcripts (≤50 terms, ≤64 characters each).

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence/config', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.put("https://api.orbit.devotel.io/api/v1/insights/sales-conversation-intelligence/config", headers=headers)
print(r.json())

{
  "data": {
    "enabled": true,
    "competitor_trackers": [
      "AcmeVoice"
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Worked sequences

The page above trims every operation past the fifteenth to cURL plus TypeScript. This section renders the first hero flow(s) past the cut in the full six-language group, so the operation a pipeline reaches next is copy-paste complete.

Get P&L labour-rate configuration

curl "https://api.orbit.devotel.io/api/v1/insights/conversation-pnl/config" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/conversation-pnl/config', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/conversation-pnl/config", headers=headers)
print(r.json())

Get cross-channel unit economics

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/insights/cost-economics', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!
  }
});
const data = await res.json();

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/insights/cost-economics", headers=headers)
print(r.json())

​Insights API

​title: “Worked insights queries” description: “LLM-spend drill-downs, anomaly rollups, agent benchmarks, attribution chains, containment trends, and quality evals — each as a full send → envelope → drill-in chain.”

​Worked insights queries

​1. Which model drove the LLM spend spike

​2. Compare anomaly scopes and page history rollups

​3. Benchmark and QA sample queries

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

​5. Containment trend + talk ratio

​6. Quality eval scores

​7. Read the LLM-spend header, trend, and leaderboard

​8. Compare agents and isolate a quality gap by language

​9. Read the spend caps before you raise them

​10. Cost to serve: conversation P&L

​11. Platform-side economics to pair with spend

​Pagination and envelope rules

​Error shapes: scope gap vs parameter issue

​Benchmark agents against the org population

​Compare AI agents side by side

​Agent quality segmented by detected language

​Get per-agent ROI summary

​Get ROI attribution configuration

​Get the daily ROI trend

​Aggregate anomaly ledger by scope

​List anomaly ledger items

​Anomaly counts over time

​List ranked automation opportunities

​Get automation ROI assumptions

​Get inbound-call marketing attribution

​Get AI-agent containment summary

​Get the daily containment trend

​Get blended cost-to-serve summary

​Get P&L labour-rate configuration

​Get cross-channel unit economics

​Get cost-economics rate configuration

​Get KB auto-draft configuration

​Get language-segmented quality summary

​Get AI budget configuration

​Get AI spend by feature

​Get AI spend by model

​Get per-model spend caps

​Get AI-spend headline stats

​Get grouped AI-spend summary

​Get AI-spend trend buckets

​Get top-spending conversations

​Get no-match miner configuration

​Get sales conversation intelligence summary

​Get sales intelligence configuration

​Run the KB auto-draft miner

​Run the no-match query miner

​Update ROI attribution configuration

​Update automation ROI assumptions

​Update P&L labour-rate configuration

​Update cost-economics rate configuration

​Update KB auto-draft configuration

​Update AI budget configuration

​Update per-model spend caps

​Update no-match miner configuration

​Update sales intelligence configuration

​Worked sequences

​Get P&L labour-rate configuration

​Get cross-channel unit economics

Insights API

title: “Worked insights queries” description: “LLM-spend drill-downs, anomaly rollups, agent benchmarks, attribution chains, containment trends, and quality evals — each as a full send → envelope → drill-in chain.”

Worked insights queries

1. Which model drove the LLM spend spike

2. Compare anomaly scopes and page history rollups

3. Benchmark and QA sample queries

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

5. Containment trend + talk ratio

6. Quality eval scores

7. Read the LLM-spend header, trend, and leaderboard

8. Compare agents and isolate a quality gap by language

9. Read the spend caps before you raise them

10. Cost to serve: conversation P&L

11. Platform-side economics to pair with spend

Pagination and envelope rules

Error shapes: scope gap vs parameter issue

Benchmark agents against the org population

Compare AI agents side by side

Agent quality segmented by detected language

Get per-agent ROI summary

Get ROI attribution configuration

Get the daily ROI trend

Aggregate anomaly ledger by scope

List anomaly ledger items

Anomaly counts over time

List ranked automation opportunities

Get automation ROI assumptions

Get inbound-call marketing attribution

Get AI-agent containment summary

Get the daily containment trend

Get blended cost-to-serve summary

Get P&L labour-rate configuration

Get cross-channel unit economics

Get cost-economics rate configuration

Get KB auto-draft configuration

Get language-segmented quality summary

Get AI budget configuration

Get AI spend by feature

Get AI spend by model

Get per-model spend caps

Get AI-spend headline stats

Get grouped AI-spend summary

Get AI-spend trend buckets

Get top-spending conversations

Get no-match miner configuration

Get sales conversation intelligence summary

Get sales intelligence configuration

Run the KB auto-draft miner

Run the no-match query miner

Update ROI attribution configuration

Update automation ROI assumptions

Update P&L labour-rate configuration

Update cost-economics rate configuration

Update KB auto-draft configuration

Update AI budget configuration

Update per-model spend caps

Update no-match miner configuration

Update sales intelligence configuration

Worked sequences

Get P&L labour-rate configuration

Get cross-channel unit economics