Worked usage samples

The chain below covers read the aggregate → page its window → stand up an alert rule → branch on the errors. The aggregate (GET /api/v1/messages/usage/records) is the Twilio-parity surface that rolls every billable row up per channel and direction with cost attribution — the exact numbers the usage-series and usage-records dashboard pages render. The cursor-windowed row-level feed behind the same pages (since/until/channel/cursor) lives on the usage records overlay; this page adds the aggregate and its alerting sibling.

1. Read the per-channel usage aggregate

GET /api/v1/messages/usage/records?days=30

Returns one record per billing category (sms-inbound, sms-outbound, mms-inbound, mms-outbound, voice-inbound, voice-outbound) over a trailing window. days (1–365, default 30) sizes the window; SMS counts by segment, MMS and voice by message. Currency stays in the group key, so a mid-window currency flip returns one record per currency bucket rather than a mixed sum. count and price are the cost-attribution pair — price is the debited amount in currency.

curl -X GET "https://api.orbit.devotel.io/api/v1/messages/usage/records?days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY })

const usage = await orbit.request(
  'GET',
  '/api/v1/messages/usage/records?days=30',
)
// usage.records — one entry per (category, channel, direction, currency)

{
  "data": {
    "period_days": 30,
    "records": [
      {
        "category": "sms-outbound",
        "channel": "sms",
        "direction": "outbound",
        "count": 12844,
        "price": 106.61,
        "currency": "USD"
      },
      {
        "category": "sms-inbound",
        "channel": "sms",
        "direction": "inbound",
        "count": 3102,
        "price": 0,
        "currency": "USD"
      },
      {
        "category": "voice-outbound",
        "channel": "voice",
        "direction": "outbound",
        "count": 417,
        "price": 38.9,
        "currency": "USD"
      }
    ]
  },
  "meta": {
    "request_id": "req_5c2f0a1e",
    "timestamp": "2026-09-10T12:00:00.000Z"
  }
}

Add country_splits=1 (also accepts true / yes) to extend each record with a countries array — a per-ISO-3166 alpha-2 breakdown of country, count, and price for that category, derived from the recipient’s E.164. Pass a smaller or larger days to re-slice the window; there is no cursor here because the aggregate returns its full category set in one body. The row-level counterpart with since/until/channel/cursor pagination is documented on the usage records page.

2. Stand up an alert rule on the same signal

POST /api/v1/usage/alert-rules

The self-serve alerting sibling on this page watches the two signals that move a usage integration: delivery (sms_delivery_rate) and volume/spend (outbound_message_volume, spend). Create at most 50 rules per organization; a threshold rule needs a comparator (gt / gte / lt / lte) and a finite threshold on the metric’s native unit — percent, count, or USD.

curl -X POST "https://api.orbit.devotel.io/api/v1/usage/alert-rules" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Idempotency-Key: usage-alert-sms-delivery-floor" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SMS delivery rate below 95%",
    "metric": "sms_delivery_rate",
    "mode": "threshold",
    "comparator": "lt",
    "threshold": 95,
    "window_days": 7,
    "cooldown_hours": 24
  }'

const rule = await orbit.request('POST', '/api/v1/usage/alert-rules', {
  name: 'SMS delivery rate below 95%',
  metric: 'sms_delivery_rate',
  mode: 'threshold',
  comparator: 'lt',
  threshold: 95,
  window_days: 7,
  cooldown_hours: 24,
})
// rule.id — PATCH or DELETE it at /api/v1/usage/alert-rules/:id

{
  "data": {
    "id": "uar_5f2c9d81",
    "name": "SMS delivery rate below 95%",
    "metric": "sms_delivery_rate",
    "metric_label": "SMS delivery rate",
    "unit": "percent",
    "direction": "higher_is_better",
    "mode": "threshold",
    "comparator": "lt",
    "threshold": 95,
    "window_days": 7,
    "notify_channels": ["in_app"],
    "enabled": true,
    "cooldown_hours": 24,
    "last_evaluated_at": null,
    "last_status": null,
    "last_value": null,
    "last_fired_at": null,
    "metric_path": "/insights",
    "created_at": "2026-09-10T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z",
    "created_by_user_id": "user_2g8h1c4f"
  },
  "meta": {
    "request_id": "req_7d3a2b8c",
    "timestamp": "2026-09-10T12:00:05.000Z"
  }
}

Each fired breach lands in GET /api/v1/usage/alert-rules/events and the in-app notification dropdown. POST /api/v1/usage/alert-rules/evaluate runs the evaluator for your organization now instead of waiting for the next sweep.

3. Error branches

Two branches decide what callers do next on this surface. Validation — a malformed rule body. POST /api/v1/usage/alert-rules validates the body before anything persists. A threshold rule missing its comparator or threshold, a metric outside the registry (sms_delivery_rate, outbound_message_volume, spend), or a window_days above 30 returns 422 VALIDATION_ERROR naming the rejected field:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "comparator is required for a threshold rule",
    "details": {
      "issues": [
        {
          "field": "comparator",
          "message": "comparator is required for a threshold rule"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_8f1c3d4b",
    "timestamp": "2026-09-10T12:00:06.000Z"
  }
}

Scope — the key lacks the usage or messages scope. Reads on this page are scope-gated: the usage aggregate under messages needs a key minted with messages:read (or messages:write), and the /usage/* reads need usage:read. A dashboard session without an accepted org role, or an API key without the scope, is rejected 403 before any query runs:

403

{
  "error": {
    "code": "FORBIDDEN",
    "status": 403,
    "message": "API key is missing the required scope: usage:read"
  },
  "meta": {
    "request_id": "req_9a4e5f6d",
    "timestamp": "2026-09-10T12:00:07.000Z"
  }
}

Treat both as terminal: fix the rule body before resending a 422, and re-mint the key with the missing scope or assign an accepted role before retrying a 403. The envelope mechanics — error.code / status / details, the retry-vs-terminal decision table — live in the error-handling guide; only the usage-specific triggers above belong here.

API Reference

All Endpoints

Worked usage samples