Dashboard stats API

The Stats endpoints under /api/v1/stats are the read platform behind Orbit’s dashboard cards, workspace overviews, and analytics pages. They are server-side authenticated (Bearer API key) and tenant-scoped, so they are also usable to build your own reporting without exporting to a warehouse. All responses use the standard envelope — data holds the payload and a meta block carries request_id and timestamp. Each code sample below is a complete paste-and-run in its language. The Node SDK (npm install @devotel-orbit/node) and the Python SDK (pip install devotel-orbit-sdk) are published; the Go SDK ships from workspace source. Every SDK call here ends by accessing the response fields — matching the response shape below each sample set. If you use Go, Java, or C#, the escape hatch section at the bottom of this page covers you.

Summary cards — one request

GET /api/v1/stats/summary returns the six home-overview cards in one read: 24-hour message volume, active agents, total contacts, 24-hour API calls, today’s spend, and the overall success rate. Each card carries its value plus the change versus the previous period where one is computed. The cards degrade gracefully to zero or empty values rather than returning a hard error on a dependency blip, which is also what makes them safe to poll.

cURL
Node
Python
Go

curl "https://api.orbit.devotel.io/api/v1/stats/summary" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });
const summary = await orbit.request('GET', '/stats/summary');

console.log(summary.data.messages_24h.value);   // 41230
console.log(summary.data.success_rate);         // 98.6

summary = client.request("GET", "/stats/summary")

print(summary["data"]["messages_24h"]["value"])  # 41230
print(summary["data"]["success_rate"])           # 98.6

var summary map[string]any
err := client.Request(context.Background(), "GET", "/stats/summary", nil, nil, &summary, "")
// summary["data"].(map[string]any)["messages_24h"].(map[string]any)["value"]

Response — 200 OK

{
  "data": {
    "messages_24h": { "label": "Messages (24h)", "value": 41230, "change": 8.4 },
    "active_agents": { "label": "Active agents", "value": 12, "change": null },
    "total_contacts": { "label": "Total contacts", "value": 184530, "change": null },
    "api_calls_24h": { "label": "API calls (24h)", "value": 102410, "change": -2.1 },
    "spend_today": { "label": "Spend today", "value": "$1,204.50", "change": null },
    "success_rate": 98.6
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-08-25T07:30:00.000Z" }
}

change is null when there is no previous period to compare against. Prefer one pulled page over per-widget polling: GET /api/v1/stats/dashboard computes the summary, per-channel health, usage timeline, and recent activity in parallel and returns them as one payload. data carries summary, channelHealth, usageTimeline, and recentActivity.

Usage timeline

GET /api/v1/stats/usage returns a daily message-volume row per channel (SMS, WhatsApp, email, voice, agents). Select the window with ?days= (default 30, max 365) or an explicit start_date / end_date pair — the explicit pair takes precedence.

cURL
Node
Python
Go

curl "https://api.orbit.devotel.io/api/v1/stats/usage?days=90" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

const usage = await orbit.request('GET', '/stats/usage?days=90');

for (const day of usage.data) {
  console.log(day.date, day.sms, day.whatsapp);  // '2026-08-01' 4021 1300
}

usage = client.request("GET", "/stats/usage?days=90")

for day in usage["data"]:
    print(day["date"], day["sms"], day["whatsapp"])  # '2026-08-01' 4021 1300

var usage map[string]any
err := client.Request(context.Background(), "GET",
    "/stats/usage", url.Values{"days": {"90"}}, nil, &usage, "")
for _, day := range usage["data"].([]any) {
    row := day.(map[string]any)
    fmt.Println(row["date"], row["sms"], row["whatsapp"])
}

Response — 200 OK

{
  "data": [
    { "date": "2026-08-01", "sms": 4021, "whatsapp": 1300, "email": 512, "voice": 44, "agents": 211 },
    { "date": "2026-08-02", "sms": 3987, "whatsapp": 1211, "email": 489, "voice": 39, "agents": 196 }
  ],
  "meta": { "request_id": "req_…", "timestamp": "2026-08-25T07:30:00.000Z" }
}

Activity feed

GET /api/v1/stats/activity returns the most recent platform activity — messages, agent events, webhook deliveries — newest first. Use ?limit= (default 20, max 100) and ?since_hours (max 8760) to bound the server-side window. The feed is a bounded recent list, not a cursor feed: raise limit and widen since_hours to see further back, and rely on next_cursor only on the request-logs endpoint below.

curl "https://api.orbit.devotel.io/api/v1/stats/activity?limit=50&since_hours=24" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

Response — 200 OK

{
  "data": [
    { "type": "message", "timestamp": "2026-08-25T07:29:41.000Z", "summary": "SMS to +14155552671 delivered" },
    { "type": "agent", "timestamp": "2026-08-25T07:29:12.000Z", "summary": "Agent support-bot answered conversation cnv_a51b…" },
    { "type": "webhook", "timestamp": "2026-08-25T07:27:58.000Z", "summary": "Delivery status webhook posted — 200 OK" }
  ],
  "meta": { "request_id": "req_…", "timestamp": "2026-08-25T07:30:00.000Z" }
}

Each item carries a type, a timestamp, and a resource summary.

Request logs — cursor pagination

GET /api/v1/stats/request-logs is the Developer → Request Logs viewer as an API: paginated, filtered API request logs for the tenant. Filter by method, status, path, api_key (key prefix), or request_id; bound the window with days or a start_date / end_date pair; page with cursor and limit (max 100, default 50).

curl "https://api.orbit.devotel.io/api/v1/stats/request-logs?limit=50&status=4xx&days=1" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

Response — 200 OK

{
  "data": {
    "entries": [
      {
        "timestamp": "2026-08-25T07:12:04.512Z",
        "method": "POST",
        "path": "/api/v1/messages",
        "status": 422,
        "latency_ms": 87,
        "ip": "203.0.113.10",
        "user_agent": "orbit-node-sdk/1.4.2",
        "request_id": "req_9f2a1c…",
        "response_size": 214,
        "trace_id": "0af7651916cd43dd8448eb211c80319c"
      }
    ],
    "next_cursor": "eyJpZCI6Im…"
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-08-25T07:30:00.000Z" }
}

next_cursor is an opaque resumable token, null when there is no further page. Filter only where you must: the status filter accepts exact codes (200) and class buckets (4xx, 5xx). Walk every page — pass the previous response’s next_cursor back as cursor until it comes back null:

Node SDK

let cursor: string | undefined;
do {
  const page = await orbit.request(
    'GET',
    `/stats/request-logs?days=1&limit=100${cursor ? `&cursor=${cursor}` : ''}`,
  );
  for (const entry of page.data.entries) {
    // consume one log entry per iteration
  }
  cursor = page.data.next_cursor ?? undefined;
} while (cursor);

Python SDK

cursor = None
while True:
    path = "/stats/request-logs?days=1&limit=100"
    if cursor:
        path += f"&cursor={cursor}"
    page = client.request("GET", path)
    for entry in page["data"]["entries"]:
        pass  # consume one log entry per iteration
    cursor = page["data"]["next_cursor"]
    if not cursor:
        break

Per-channel statistics and health

Each channel has a dedicated stats endpoint that powers its workspace overview cards:

GET /api/v1/stats/sms — total outbound SMS, delivered and failed counts, the terminal delivery rate, and average delivery latency.
GET /api/v1/stats/whatsapp — total conversations, sent and received message counts, terminal delivery rate, and read rate.
GET /api/v1/stats/voice — total calls split inbound and outbound, plus average call duration.
GET /api/v1/stats/agents — agent counts and conversation counts with the active totals.
GET /api/v1/stats/contacts — contact count, contacts created in the last 30 days, and the resulting growth rate.
GET /api/v1/stats/flows — flow and published-flow counts, plus aggregate execution totals.
GET /api/v1/stats/numbers — number inventory: total, active, SMS-capable, and voice-capable counts.
GET /api/v1/stats/channel-health — per-channel delivery and connect-quality signal as rendered by the Messages hub.
GET /api/v1/stats/gateway/sms — rolling 24-hour SMS gateway health (status, latency, and counts), so availability and delivery performance can be shown as separate dimensions.

Advanced analytics

The /api/v1/stats/analytics/* routes serve the deeper breakdown the Insights dashboards render — daily volume, the delivery funnel, channel and geographic breakdown, peak hours with the tenant timezone, cost by channel, and top recipients. They require the advanced-analytics flag for your account and return 403 otherwise.

GET /api/v1/stats/analytics — the full payload for the window.
GET /api/v1/stats/analytics/summary — only the consolidated counts, cheaper than the full payload.
GET /api/v1/stats/analytics/channels — per-channel breakdown (volume, outcome, spend).
GET /api/v1/stats/analytics/volume — daily sent and delivered counts.
GET /api/v1/stats/analytics/delivery — the delivery funnel with counts per stage.

All of them accept ?days= (default 30, max 365) or an explicit start_date / end_date pair. To enable advanced analytics for your account, contact support.

ESG / carbon reporting

The sustainability report is served from /api/v1/stats/analytics/carbon and /api/v1/stats/analytics/carbon/export (CSV). See the Sustainability and ESG reporting guide for the full contract.

Escape hatch for Go, Java, and C#

No SDK wraps the stats endpoints with typed methods today — the samples above use the same low-level request method every SDK ships for uncovered routes. The pattern is identical across languages: client.Request(ctx, method, path, query, body, out) in Go, client.request(method, path, query, body) in Java, and client.RequestAsync(method, path, query, body) in C#. A 90-day usage pull plus the per-channel SMS card:

query := url.Values{"days": {"90"}}
var usage map[string]any
err := client.Request(context.Background(), "GET", "/stats/usage", query, nil, &usage, "")

var sms map[string]any
err = client.Request(context.Background(), "GET", "/stats/sms", nil, nil, &sms, "")

Java — source-only SDK; vendor from the monorepo — see the [Java SDK](/sdks/java) page.

Map<String, Object> usage = client.request("GET", "/stats/usage",
    Map.of("days", "90"), null);
Map<String, Object> sms = client.request("GET", "/stats/sms", null, null);

var usage = await client.RequestAsync("GET", "/stats/usage",
    query: new Dictionary<string, object?> { ["days"] = "90" });
var sms = await client.RequestAsync("GET", "/stats/sms");

The workaround also applies to Python and Node when you have not added the SDK: call the REST path directly with the same envelope contract. Scope per language, and the authoritative list of what each SDK wraps, is on the SDK index.

Polling and rate limits

These routes are read-only and tenant-scoped; they are safe to poll, and many power always-on dashboard widgets. Pull a unified payload with /api/v1/stats/dashboard instead of fanning out per widget when you render a single page. If you see a 403 from the advanced-analytics routes only, that is the feature flag, not an auth failure — the rest of /stats still answers 200.

Metric to endpoint map

Metric	Endpoint
Home overview cards (volume, agents, contacts, API calls, spend, success rate)	`GET /api/v1/stats/summary`
One pulled dashboard page (cards + health + timeline + activity)	`GET /api/v1/stats/dashboard`
Daily message volume per channel	`GET /api/v1/stats/usage`
Recent platform activity feed	`GET /api/v1/stats/activity`
Tenant API request logs	`GET /api/v1/stats/request-logs`
Per-channel totals and delivery health	`GET /api/v1/stats/<sms\|whatsapp\|voice\|agents\|contacts\|flows\|numbers>`
Deep breakdowns (funnel, geography, cost, recipients)	`GET /api/v1/stats/analytics/*` (flagged)
ESG carbon report and CSV export	`GET /api/v1/stats/analytics/carbon(/export)`

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Dashboard stats API

Dashboard stats API

Summary cards — one request

Usage timeline

Activity feed

Per-channel statistics and health

Advanced analytics

ESG / carbon reporting

Escape hatch for Go, Java, and C#

Polling and rate limits

Metric to endpoint map

​Dashboard stats API

​Summary cards — one request

​Usage timeline

​Activity feed

​Request logs — cursor pagination

​Per-channel statistics and health

​Advanced analytics

​ESG / carbon reporting

​Escape hatch for Go, Java, and C#

​Polling and rate limits

​Metric to endpoint map

Dashboard stats API

Summary cards — one request

Usage timeline

Activity feed

Request logs — cursor pagination

Per-channel statistics and health

Advanced analytics

ESG / carbon reporting

Escape hatch for Go, Java, and C#

Polling and rate limits

Metric to endpoint map