Analytics API

Aggregated analytics over message traffic, deliverability, costs, and goal conversions. All read endpoints are served from a database read-replica, so they’re cheap to call but lag the primary by 1-3 seconds. Base path: /api/v1/analytics Authentication: API key (X-API-Key) or session JWT.

Message analytics

Method	Path	Purpose
`GET`	`/api/v1/analytics/messages`	Message volume, status breakdown, time series
`GET`	`/api/v1/analytics/messages/by-channel`	Volume per channel
`GET`	`/api/v1/analytics/messages/by-country`	Volume per destination country
`GET`	`/api/v1/analytics/messages/errors`	Error-code rollup
`GET`	`/api/v1/analytics/costs`	Cost per channel / country / day
`GET`	`/api/v1/analytics/deliverability`	Delivery, read, click rates

Scheduled reports

Email-delivered analytics rollups on a schedule.

Method	Path	Purpose
`GET`	`/api/v1/analytics/scheduled-reports`	List
`POST`	`/api/v1/analytics/scheduled-reports`	Create
`PATCH`	`/api/v1/analytics/scheduled-reports/{id}`	Update
`DELETE`	`/api/v1/analytics/scheduled-reports/{id}`	Delete
`POST`	`/api/v1/analytics/scheduled-reports/{id}/send-now`	Trigger an out-of-band run

Conversion goals

A goal is a tracked conversion (signup, purchase, trial start, etc.). Hits are recorded server-side via record, or via the /g/:goalId/:contactId.gif tracking pixel for browser conversion attribution.

Method	Path	Purpose
`GET`	`/api/v1/analytics/goals/`	List goals
`POST`	`/api/v1/analytics/goals/`	Create a goal
`GET`	`/api/v1/analytics/goals/{id}`	Get a goal
`PATCH`	`/api/v1/analytics/goals/{id}`	Update
`DELETE`	`/api/v1/analytics/goals/{id}`	Delete
`POST`	`/api/v1/analytics/goals/{id}/record`	Record a conversion server-side
`GET`	`/api/v1/analytics/goals/{id}/conversions`	List conversions
`GET`	`/api/v1/analytics/goals/{id}/stats`	Conversion rate, attribution rollup

Examples

Every response lands in the standard envelope: the payload under data, and meta.request_id / meta.timestamp alongside. Examples below trim the meta block. The Node SDK (new Orbit({ apiKey })) isn’t published to a registry yet — call any endpoint through its generic orbit.request() helper until the typed resource catches up.

Message volume time series — GET /analytics/messages

Query params: start_date / end_date (YYYY-MM-DD or ISO datetime, max 365-day range), plus days as a rolling-window shortcut; optional channel, status, campaign_id, and group_by (hour | day | week | month, default day).

curl "https://api.orbit.devotel.io/api/v1/analytics/messages?start_date=2026-08-01&end_date=2026-08-25&group_by=day" \
  -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 res = await orbit.request(
  "GET",
  "/analytics/messages?start_date=2026-08-01&end_date=2026-08-25&group_by=day",
);
// res.data.time_series — one bucket per day

Response 200 — data.totals covers the whole window; data.time_series carries one bucket per group_by period. period is the bucket’s UTC start and period_date is the tenant-local calendar date for that bucket:

{
  "data": {
    "totals": {
      "total_sent": 48213,
      "total_delivered": 46910,
      "total_failed": 1187,
      "total_read": 21442,
      "delivery_rate": 97.3,
      "read_rate": 45.71,
      "avg_delivery_time_ms": 2140
    },
    "time_series": [
      {
        "period": "2026-08-24T00:00:00.000Z",
        "period_date": "2026-08-24",
        "total_sent": 2011,
        "total_delivered": 1957,
        "total_failed": 51,
        "total_read": 902,
        "delivery_rate": 97.31,
        "read_rate": 46.09,
        "avg_delivery_time_ms": 2380
      }
    ],
    "group_by": "day"
  }
}

If no messages match the window, you still get a 200 with zeroed totals and an empty time_series.

Per-channel breakdown — GET /analytics/messages/by-channel

Same date window params as above, no group_by — one rollup row per channel. WhatsApp tenants with multiple connections can pass phone_number_id to scope the breakdown to one sending number.

curl "https://api.orbit.devotel.io/api/v1/analytics/messages/by-channel?start_date=2026-08-01&end_date=2026-08-25" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const res = await orbit.request(
  "GET",
  "/analytics/messages/by-channel?start_date=2026-08-01&end_date=2026-08-25",
);
// res.data.channels — one row per channel

Response 200 — engagement counters (total_opened, total_clicked, total_complained, total_soft_bounced) are email-relevant and read 0 on channels that never stamp them:

{
  "data": {
    "channels": [
      {
        "channel": "sms",
        "total_sent": 31002,
        "total_delivered": 30111,
        "total_failed": 891,
        "total_read": 0,
        "total_opened": 0,
        "total_opened_genuine": 0,
        "total_clicked": 0,
        "total_complained": 0,
        "total_soft_bounced": 0,
        "total_scheduled": 412,
        "delivery_rate": 97.13,
        "read_rate": 0,
        "avg_delivery_time_ms": 1805
      },
      {
        "channel": "whatsapp",
        "total_sent": 17211,
        "total_delivered": 16799,
        "total_failed": 296,
        "total_read": 21442,
        "total_opened": 0,
        "total_opened_genuine": 0,
        "total_clicked": 0,
        "total_complained": 0,
        "total_soft_bounced": 0,
        "total_scheduled": 0,
        "delivery_rate": 97.61,
        "read_rate": 62.3,
        "avg_delivery_time_ms": 2690
      }
    ]
  }
}

Delivery / read / failure rates — GET /analytics/deliverability

channel is required (sms, whatsapp, rcs, email, voice, instagram, messenger, viber). window is 24h | 7d | 30d (default 7d), and groupBy overrides the bucket size (hour, default for 24h; day otherwise). Results are cached for 60 seconds, so plan for up to a minute of staleness on top of the read-replica lag.

curl "https://api.orbit.devotel.io/api/v1/analytics/deliverability?channel=sms&window=7d&groupBy=day" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const res = await orbit.request(
  "GET",
  "/analytics/deliverability?channel=sms&window=7d&groupBy=day",
);
// res.data.series — one bucket per day; rates under data.delivery_rate read directly

Response 200 — rates use terminal-status messages as the denominator so in-flight sends don’t deflate the success number; timezone names the zone the series buckets were aligned on (render the x-axis labels in that zone, not the browser’s):

{
  "data": {
    "channel": "sms",
    "window": "7d",
    "groupBy": "day",
    "timezone": "America/New_York",
    "totals": {
      "sent": 14120,
      "accepted": 14120,
      "delivered": 13719,
      "read": 0,
      "terminal": 14001,
      "failed": 282,
      "bounced": 0,
      "complained": 0,
      "unsubscribed": 14
    },
    "series": [
      {
        "ts": "2026-08-24T04:00:00.000Z",
        "sent": 2011,
        "accepted": 2011,
        "delivered": 1957,
        "read": 0,
        "terminal": 2002,
        "failed": 45,
        "bounced": 0,
        "complained": 0,
        "unsubscribed": 2
      }
    ],
    "delivery_rate": 97.99,
    "read_rate": 0,
    "failure_rate": 2.01,
    "top_failure_reasons": [
      { "reason": "30008", "count": 72 },
      { "reason": "UNKNOWN", "count": 210 }
    ],
    "top_failure_countries": [
      { "country": "IN", "count": 88, "rate": 6.4 }
    ]
  }
}

Conversion attribution round trip — goals

A full attribution loop is four calls: create the goal, record conversions for it, then read the aggregated stats. Goal writes (POST / PATCH / DELETE, plus record) require the owner, admin, or developer role; reads are open to any authenticated member. 1 — Create the goal. type is one of pixel_fire, webhook_hit, manual, tag_added, custom_event; attribution_model is last_touch (default), first_touch, linear, or time_decay; lookback_days bounds how far back a touchpoint may claim credit (1–180, default 7).

curl -X POST https://api.orbit.devotel.io/api/v1/analytics/goals \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout completed",
    "type": "webhook_hit",
    "value_cents": 9900,
    "lookback_days": 14,
    "attribution_model": "last_touch"
  }'

const created = await orbit.request("POST", "/analytics/goals", {
  name: "Checkout completed",
  type: "webhook_hit",
  value_cents: 9900,
  lookback_days: 14,
  attribution_model: "last_touch",
});
const goalId = created.data.id;

Response 201:

{
  "data": {
    "id": "goal_3f8cPaLm2x",
    "name": "Checkout completed",
    "type": "webhook_hit",
    "config": {},
    "value_cents": 9900,
    "lookback_days": 14,
    "attribution_model": "last_touch",
    "enabled": true,
    "created_at": "2026-08-25T14:02:11.831Z",
    "updated_at": "2026-08-25T14:02:11.831Z"
  }
}

2 — Record a conversion. The body accepts contact_id (optional), value_cents (overrides the goal’s default), and arbitrary metadata. Server-to-server callers outside a session must also pass Authorization: HMAC <contactId>:<sig>, where sig is the HMAC-SHA256 of the string <goal_id>:<contactId> computed with your API secret — an unsigned public request is rejected with 401.

curl -X POST https://api.orbit.devotel.io/api/v1/analytics/goals/goal_3f8cPaLm2x/record \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_9kx2Lp",
    "value_cents": 9900,
    "metadata": { "order_id": "ord_12345" }
  }'

const recorded = await orbit.request(
  "POST",
  `/analytics/goals/${goalId}/record`,
  {
    contact_id: "contact_9kx2Lp",
    value_cents: 9900,
    metadata: { order_id: "ord_12345" },
  },
);

Response 201 — each conversion is written once per enabled attribution model the goal defines (usually one), and the ids below point back at the message / campaign / agent the goal’s model credited:

{
  "data": {
    "written": 1,
    "conversions": [
      {
        "id": "gcv_8be1Rt4M",
        "goal_id": "goal_3f8cPaLm2x",
        "contact_id": "contact_9kx2Lp",
        "value_cents": 9900,
        "attributed_message_id": "msg_7a2eWq",
        "attributed_campaign_id": "camp_91HzT2",
        "attributed_agent_id": null,
        "conversion_time": "2026-08-25T14:11:47.002Z",
        "metadata": { "order_id": "ord_12345" }
      }
    ]
  }
}

3 — Read the goal stats. window_days (1–365, default 30) bounds which conversions count.

curl "https://api.orbit.devotel.io/api/v1/analytics/goals/goal_3f8cPaLm2x/stats?window_days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const stats = await orbit.request(
  "GET",
  `/analytics/goals/${goalId}/stats?window_days=30`,
);

Response 200 — top-10 buckets per attribution axis:

{
  "data": {
    "goal_id": "goal_3f8cPaLm2x",
    "window_days": 30,
    "conversions": 312,
    "total_value_cents": 3088800,
    "top_attributed_messages": [
      { "id": "msg_7a2eWq", "count": 41 }
    ],
    "top_attributed_campaigns": [
      { "id": "camp_91HzT2", "count": 118 }
    ],
    "top_attributed_agents": []
  }
}

Tracking pixels for browser conversions. Goals of type pixel_fire get a pixel_url hint back on the list/get responses. Embed a 1×1 image; the endpoint answers GET /g/:goalId/:contactId.gif?sig=<sig>&schema=<schema> with the pixel and no-cache headers (200 whether or not the conversion recorded, so the merchant page never shows a broken image). sig is the HMAC-SHA256 hex of <goal_id>:<contact_id>:<tenant_schema> using your API secret, and schema is your tenant schema name (both shown in the dashboard’s goal detail page). Signing the schema into the payload means a valid pixel from one workspace can’t mint a conversion in another.

Scheduled reports — create and trigger

Report writes require owner or admin. type is one of messaging_volume, deliverability, top_contacts, spend, custom (custom runs the saved query in filters); frequency is daily | weekly | monthly, anchored to 09:00 in the report’s timezone (UTC when omitted). recipients takes 1–50 emails, as an array or a comma-separated string. Create:

curl -X POST https://api.orbit.devotel.io/api/v1/analytics/scheduled-reports \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly deliverability digest",
    "type": "deliverability",
    "frequency": "weekly",
    "recipients": ["ops@example.com"],
    "timezone": "America/New_York"
  }'

const report = await orbit.request("POST", "/analytics/scheduled-reports", {
  name: "Weekly deliverability digest",
  type: "deliverability",
  frequency: "weekly",
  recipients: ["ops@example.com"],
  timezone: "America/New_York",
});

Response 201 — next_send_at is the upcoming cadence tick, not an internal trigger value; a PATCH that changes frequency recomputes it from the new cadence:

{
  "data": {
    "id": "srep_6dT2nX9pQa",
    "organization_id": "org_2aBcDeFgH",
    "name": "Weekly deliverability digest",
    "type": "deliverability",
    "frequency": "weekly",
    "recipients": ["ops@example.com"],
    "filters": null,
    "enabled": true,
    "timezone": "America/New_York",
    "last_sent_at": null,
    "next_send_at": "2026-08-31T09:00:00-04:00",
    "created_by": "user_9fE1Kl",
    "created_at": "2026-08-25T15:20:04.118Z",
    "updated_at": "2026-08-25T15:20:04.118Z"
  }
}

Trigger an out-of-band run. Queues the report for immediate delivery without waiting for the next tick; the dashboard polls last_sent_at to show progress.

curl -X POST https://api.orbit.devotel.io/api/v1/analytics/scheduled-reports/srep_6dT2nX9pQa/send-now \
  -H "X-API-Key: dv_live_sk_your_key_here"

await orbit.request(
  "POST",
  `/analytics/scheduled-reports/${report.data.id}/send-now`,
);

Response 200:

{
  "data": {
    "id": "srep_6dT2nX9pQa",
    "queued": true,
    "message": "Report queued for immediate delivery"
  }
}

Reconcile API numbers against a dashboard tile

The dashboard reads the same aggregation endpoints you call here, so a KPI tile should match a curl response field for field when both cover the same window. Worked example: verify the Verified CTR tile on Insights → SMS click-throughs:

curl "https://api.orbit.devotel.io/api/v1/analytics/sms-click-through?group=campaign&window=7d" \
  -H "X-API-Key: dv_live_sk_your_key_here"

The tile shows totals.verified_click_rate from that response — 0.0604 in the SMS click-through parity sample renders as 6.04%. The same mapping holds everywhere: each tile is one field under data.totals, and the full set of buckets sits under data.rows. If the tile and the API disagree, check three things before suspecting a bug:

Window mismatch — the curl window (or start_date/end_date) must equal the dashboard’s selected range.
Grouping mismatch — same-window tiles can differ when one side groups by campaign and the other by queue.
Caching — aggregations cache for up to 60 seconds, and every read rides the read-replica (1–3 seconds of lag), so refresh both sides before comparing very recent sends.

A gap that persists across matching windows and a cache-age wait is worth a support ticket — include the meta.request_id from the curl response.

Paginate buckets with the Node SDK

Aggregation endpoints that list rows (/analytics/messages/by-country, /analytics/goals/{id}/conversions, /analytics/sms-click-through) are page-numbered rather than cursor-paginated — increment page until totalPages, or once you hold every row. The totals block already covers the whole window, so you can render the KPI header from page one and only page for the table:

import { Orbit } from "@devotel-orbit/node";

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

const buckets = [];
let page = 1;

while (true) {
  const res = await orbit.request(
    "GET",
    `/analytics/sms-click-through?group=queue&window=30d&page=${page}&pageSize=100`,
  );
  buckets.push(...res.data.rows);

  const { totalPages } = res.data.pagination;
  if (page >= totalPages) break;
  page += 1;
}

// res.data.totals from any page already covers the whole window.

The cursor variant (meta.pagination.cursor / has_more) applies to record-list endpoints like GET /messages — walk it the same way, passing the cursor back until has_more is false. The full model is in the Pagination guide.

API Reference

All Endpoints

Analytics API: message metrics and scheduled reports

Analytics API

Message analytics

Scheduled reports

Conversion goals

Examples

Message volume time series — GET /analytics/messages

Per-channel breakdown — GET /analytics/messages/by-channel

Delivery / read / failure rates — GET /analytics/deliverability

Conversion attribution round trip — goals

Scheduled reports — create and trigger

Reconcile API numbers against a dashboard tile

Paginate buckets with the Node SDK

See also

​Analytics API

​Message analytics

​Scheduled reports

​Conversion goals

​Examples

​Message volume time series — GET /analytics/messages

​Per-channel breakdown — GET /analytics/messages/by-channel

​Delivery / read / failure rates — GET /analytics/deliverability

​Conversion attribution round trip — goals

​Scheduled reports — create and trigger

​Reconcile API numbers against a dashboard tile

​Paginate buckets with the Node SDK

​See also

Analytics API

Message analytics

Scheduled reports

Conversion goals

Examples

Message volume time series — GET /analytics/messages

Per-channel breakdown — GET /analytics/messages/by-channel

Delivery / read / failure rates — GET /analytics/deliverability

Conversion attribution round trip — goals

Scheduled reports — create and trigger

Reconcile API numbers against a dashboard tile

Paginate buckets with the Node SDK

See also