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.

Reading the dashboard cards

Use the endpoints the dashboard itself uses. They degrade gracefully to empty or zero values rather than returning a hard error on a dependency blip, which is also what makes them safe to poll.

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.

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

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.

Unified dashboard payload

GET /api/v1/stats/dashboard computes the summary, per-channel health, usage timeline, and recent activity in parallel and returns them as one payload. Prefer this over polling the four widget routes individually — each leg shares the cache keys with those routes.

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

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 "https://api.orbit.devotel.io/api/v1/stats/usage?days=90" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

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

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.

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.

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

Request logs

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"

Each entry carries the timestamp, method, path, status, latency in ms, caller IP, user agent, request id, response size, and a W3C trace id for cross-system correlation. next_cursor is null when there is no further page.

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.

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.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Dashboard stats API

Dashboard stats API

Reading the dashboard cards

Summary cards — one request

Unified dashboard payload

Usage timeline

Per-channel statistics and health

Activity feed

Request logs

Advanced analytics

ESG / carbon reporting

Polling and rate limits

​Dashboard stats API

​Reading the dashboard cards

​Summary cards — one request

​Unified dashboard payload

​Usage timeline

​Per-channel statistics and health

​Activity feed

​Request logs

​Advanced analytics

​ESG / carbon reporting

​Polling and rate limits

Dashboard stats API

Reading the dashboard cards

Summary cards — one request

Unified dashboard payload

Usage timeline

Per-channel statistics and health

Activity feed

Request logs

Advanced analytics

ESG / carbon reporting

Polling and rate limits