Worked analytics queries

Every operation below is documented on this page with its parameters, but the bodies you branch on — the KPI envelope, the breakdown rows, the totals line — are easiest to learn as one reader chain: pick a metric/summary endpoint → filter by period and channel → page through the breakdown rows → read the totals row. The samples below walk that chain end to end and show the full response envelope at each step. Scope of this overlay:

Per the language note above, these samples show cURL and TypeScript — the two most-requested languages. The other four tabs appear on the endpoint blocks themselves.
The full endpoint catalogue with every filter combination lives at the stats API guide; recurring email delivery of the same data (schedule, recipients, cadence) is covered in scheduled reports. This overlay stays envelope-accurate: request, response, and the errors that decide what you branch on — nothing else.

All analytics reads are tenant-scoped and read-only. They degrade to a zeroed summary or an empty rows array — still a 200 — during a transient storage blip, so a poll loop or an always-on dashboard never flashes a 5xx; design your polling against that contract.

1. Pull a KPI summary

GET /api/v1/analytics/messages returns the headline KPIs for a period — sent, delivered, failed, read, the derived rates, and the average delivery time — plus a bucketed time series for charting. Filter the window with start_date / end_date (or a days lookback) and narrow to one channel with channel.

curl -G "https://api.orbit.devotel.io/api/v1/analytics/messages" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "start_date=2026-08-01" \
  --data-urlencode "end_date=2026-08-02" \
  --data-urlencode "channel=whatsapp" \
  --data-urlencode "group_by=day" \
  --data-urlencode "status=delivered"

const url = new URL("https://api.orbit.devotel.io/api/v1/analytics/messages");
url.searchParams.set("start_date", "2026-08-01");
url.searchParams.set("end_date", "2026-08-02");
url.searchParams.set("channel", "whatsapp");
url.searchParams.set("group_by", "day");
url.searchParams.set("status", "delivered");

const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const body = await res.json();
// Chart `data.time_series`; show the totals row from `data.totals`.
console.log(body.data.totals.delivery_rate);

200

{
  "data": {
    "totals": {
      "total_sent": 17150,
      "total_delivered": 16899,
      "total_failed": 251,
      "total_read": 12042,
      "delivery_rate": 98.54,
      "read_rate": 71.26,
      "avg_delivery_time_ms": 1840
    },
    "time_series": [
      {
        "period": "2026-08-01T00:00:00.000Z",
        "period_date": "2026-08-01",
        "total_sent": 2450,
        "total_delivered": 2416,
        "total_failed": 34,
        "total_read": 1720,
        "delivery_rate": 98.61,
        "read_rate": 71.19,
        "avg_delivery_time_ms": 1795
      }
    ],
    "group_by": "day"
  },
  "meta": {
    "request_id": "req_9f2c1a7b",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Adopt the same envelope shape everywhere on this page: all counters live under data.totals, chartable buckets under data.time_series (or a named breakdown array), and the echoed granularity under data.group_by. The cost counterpart — GET /api/v1/analytics/costs — answers with the same totals + time_series envelope plus a by_channel breakdown.

2. Page a breakdown series

Breakdown endpoints return the counters you just read, re-sliced per dimension — channel, destination country, or error code behind failures. Page through the list endpoints that carry a cursor (for example goals): keep the same filters, pass the previous page’s nextCursor back as cursor, and stop when it comes back null. GET /api/v1/analytics/goals

curl -G "https://api.orbit.devotel.io/api/v1/analytics/goals/" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "limit=2"

const all = [];
let cursor: string | undefined;
do {
  const url = new URL("https://api.orbit.devotel.io/api/v1/analytics/goals/");
  url.searchParams.set("limit", "2");
  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.nextCursor ?? undefined;
} while (cursor);

Page 1:

200

{
  "data": {
    "items": [
      {
        "id": "goal_7Fb2c1a7b",
        "name": "Checkout completed",
        "type": "pixel_fire",
        "enabled": true,
        "total_conversions": 312,
        "total_revenue_cents": 1559688
      },
      {
        "id": "goal_4Dc8e2b91",
        "name": "Demo booked",
        "type": "webhook_hit",
        "enabled": true,
        "total_conversions": 57,
        "total_revenue_cents": 0
      }
    ],
    "total": 3,
    "nextCursor": "cur_8Kw2mQ1z"
  },
  "meta": {
    "request_id": "req_9f2c1a7c",
    "timestamp": "2026-08-02T12:00:10.000Z"
  }
}

Page 2 — pass cursor=cur_8Kw2mQ1z; when this page’s nextCursor is null you have the full set:

200

{
  "data": {
    "items": [
      {
        "id": "goal_9Ae1f03cc",
        "name": "Upgrade started",
        "type": "manual",
        "enabled": false,
        "total_conversions": 12,
        "total_revenue_cents": 12000
      }
    ],
    "total": 3,
    "nextCursor": null
  },
  "meta": {
    "request_id": "req_9f2c1a7d",
    "timestamp": "2026-08-02T12:00:11.000Z"
  }
}

The fixed-shape breakdowns — GET /api/v1/analytics/messages/by-channel, /by-country, and /messages/errors — are single-response reads with no cursor; each returns its full ranked array (channels, countries, errors) so you render them directly.

3. Prebuilt report read (and the empty-period shape)

GET /api/v1/analytics/scheduled-reports lists the recurring reports already scheduled for your organization — the prebuilt views the scheduler emails on a cadence — with each report’s type, frequency, recipients, and its last- and next-send timestamps.

curl -G "https://api.orbit.devotel.io/api/v1/analytics/scheduled-reports" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "limit=50"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/analytics/scheduled-reports",
);
url.searchParams.set("limit", "50");
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
console.log(await res.json());

200

{
  "data": {
    "items": [
      {
        "id": "rpt_7c1f0a",
        "name": "Weekly deliverability",
        "type": "deliverability",
        "frequency": "weekly",
        "recipients": ["ops@acme.com"],
        "enabled": true,
        "timezone": "America/New_York",
        "last_sent_at": "2026-07-26T13:00:00.000Z",
        "next_send_at": "2026-08-02T13:00:00.000Z"
      }
    ],
    "total": 1,
    "nextCursor": null
  },
  "meta": {
    "request_id": "req_9f2c1a7e",
    "timestamp": "2026-08-02T12:00:12.000Z"
  }
}

The empty period is a zeroed summary, not an error. Choose a window with no traffic (or hit the degraded path during a storage blip) and the KPI endpoint still returns 200 with zeroed totals and an empty series — test your client against this shape so a quiet period never parses as a failure:

200

{
  "data": {
    "totals": {
      "total_sent": 0,
      "total_delivered": 0,
      "total_failed": 0,
      "total_read": 0,
      "delivery_rate": 0,
      "read_rate": 0,
      "avg_delivery_time_ms": 0
    },
    "time_series": [],
    "group_by": "day"
  },
  "meta": {
    "request_id": "req_9f2c1a7f",
    "timestamp": "2026-08-02T12:00:13.000Z"
  }
}

4. Errors

Two branches cover the mistakes callers actually hit on this surface. Validation — unrecognized filter value. Query params are validated before any query runs. A failed validation returns 422 VALIDATION_ERROR with error.details.issues listing each rejected field — for example a group_by outside the allowed set (hour / day / week / month):

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "Invalid query parameters",
    "details": {
      "issues": [
        {
          "field": "group_by",
          "message": "Invalid enum value. Expected 'hour' | 'day' | 'week' | 'month', received 'minute'"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_9f2c1a80",
    "timestamp": "2026-08-02T12:00:14.000Z"
  }
}

Role — reads are gated to specific roles. The analytics reads on this page require an org role of owner, admin, developer, or viewer (writes such as creating goals or scheduled reports narrow to owner, admin, and developer); a key presented without one of those roles is rejected with 403 INSUFFICIENT_PERMISSIONS and a message naming the accepted roles:

403

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "status": 403,
    "message": "This action requires one of: owner, admin, developer, viewer"
  },
  "meta": {
    "request_id": "req_9f2c1a81",
    "timestamp": "2026-08-02T12:00:15.000Z"
  }
}

Treat both as terminal, not retriable: the 422 needs a corrected filter before you re-send, and a 403 will not succeed until the role changes.

API Reference

All Endpoints

Worked analytics queries