> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard stats API

> Power your own dashboards with Orbit's tenant-scoped stats endpoints — summary cards, usage timelines, per-channel health, request logs, and advanced analytics with an explicit window.

# 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.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/stats/summary" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

**Response — 200 OK**

```json theme={null}
{
  "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.

```bash theme={null}
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.

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

**Response — 200 OK**

```json theme={null}
{
  "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.

```bash theme={null}
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).

```bash theme={null}
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](/guides/sustainability-esg-reporting) 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.