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.
The closing section, Response envelopes for the generated shells, groups the remaining analytics operations — dashboards, carrier and route truth, satisfaction goals, portfolio intelligence, and scheduled-report writes — into five panels with one copyable envelope each.

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.

Response envelopes for the generated shells

The endpoint blocks on this page carry parameters and status codes, but a number of operations render with a bare data shell in the generated reference. This section hands you one copyable, field-accurate envelope per operation, grouped into five panels so you land on the one you need: dashboards and widgets, carrier and route truth, satisfaction goals, portfolio and campaign intelligence, and scheduled-report writes. Every envelope below is tenant-scoped, wraps in the standard meta block (request_id, timestamp) shown in sections 1–4 — omitted here for readability — and degrades to zeroed or empty collections with a 200 during a transient storage blip, per the contract at the top of this page.

Dashboards and widgets

GET /api/v1/analytics/dashboards/widgets is the palette for the no-code dashboard builder: every composable widget with the read-only source endpoint that backs it, plus the grid constraints the builder enforces. It takes no query parameters.

200

{
  "data": {
    "widgets": [
      {
        "id": "sms_volume",
        "title": "SMS volume",
        "category": "messaging",
        "source": "/api/v1/analytics/messaging-insights",
        "viz": "bar",
        "default_size": { "w": 6, "h": 2 },
        "params": { "window": "7d" }
      }
    ],
    "categories": ["messaging", "voice", "email"],
    "grid": { "columns_default": 12, "max_widgets": 24 }
  }
}

GET /api/v1/analytics/deliverability answers with the per-channel deliverability panel: totals, the canonical rates, a bucketed series, and the top failure reasons and countries for one channel (channel required; window 24h|7d|30d; optional groupBy).

200

{
  "data": {
    "channel": "sms",
    "window": "7d",
    "groupBy": "day",
    "timezone": "America/New_York",
    "totals": {
      "sent": 52480,
      "accepted": 52410,
      "delivered": 51204,
      "read": 30112,
      "terminal": 51801,
      "failed": 597,
      "bounced": 210,
      "complained": 4,
      "unsubscribed": 38
    },
    "delivery_rate": 0.988,
    "read_rate": 0.585,
    "failure_rate": 0.011,
    "top_failure_reasons": [{ "reason": "invalid_number", "count": 311 }],
    "top_failure_countries": [{ "country": "US", "count": 402, "rate": 0.8 }]
  }
}

GET /api/v1/analytics/deliverability-health-center is the cross-channel deliverability cockpit: one composite 0–100 score over the five per-channel sender-reputation cards (SMS route quality, email domain and IP authentication, WhatsApp quality rating, RCS sender status, voice call quality), each independently fail-safe, plus the worst-first remediation list. days (1–90, default 7) sizes the SMS route-quality slice.

200

{
  "data": {
    "score": 86,
    "tier": "good",
    "channels": [
      {
        "key": "sms",
        "label": "SMS route quality",
        "score": 91,
        "status": "healthy",
        "detail": "3 routes scored",
        "severity": null
      }
    ],
    "channels_scored": 4,
    "channels_total": 5,
    "issues": [
      {
        "key": "email",
        "label": "Email authentication",
        "score": 62,
        "severity": "warn",
        "detail": "DMARC missing on one sending domain",
        "remediation": "Publish a DMARC record for send.acme.example"
      }
    ],
    "window_days": 7
  }
}

GET /api/v1/analytics/funnel/{step}/drop-reasons returns the ranked carrier rejection codes behind one funnel step — the same drop-reason vocabulary as the errors breakdown in section 2 — so a step’s drop-off and its causes parse with one shape.

Carrier and route truth

These four reads are the “the DLR says delivered, but is it?” panel. The silent-drop inference compares the carrier-claimed delivery rate against an engagement signal over a sliding window: a destination that reports delivered but never replies, answers, or raises any other engagement inside the window counts toward inferred_dropped, and a carrier whose engagement-backed rate stays under the drop-rate threshold over a sufficient sample flips silent_drop_suspected to true. The same sliding-window fields the handler returns are echoed on every response — dropRateThreshold (default 92), silentWindowHours (default 4 for the SMS DLR grace window), and minSampleSize — so you can audit each verdict against your own thresholds; the account health score uses that same 24-hour engagement window for its Engagement subscore. GET /api/v1/analytics/per-mno-delivery buckets outbound SMS or voice traffic by destination carrier. This row is a real silent-drop verdict: the carrier claims 1,178 delivered of 1,204 terminal, but only 610 ever showed engagement, so 568 sends are inferred dropped and the carrier trips the threshold.

200

{
  "data": {
    "channel": "sms",
    "window": "24h",
    "dropRateThreshold": 92,
    "silentWindowHours": 4,
    "minSampleSize": 250,
    "buckets": [
      {
        "mccmnc": "310410",
        "carrier_name": "Example Wireless",
        "country": "US",
        "provider": "devotel-switch",
        "terminal": 1204,
        "delivered": 1178,
        "failed": 26,
        "delivered_with_engagement": 610,
        "delivery_rate": 97.84,
        "engagement_rate": 50.66,
        "inferred_dropped": 568,
        "silent_drop_suspected": true
      }
    ],
    "totals": {
      "terminal": 1204,
      "delivered": 1178,
      "failed": 26,
      "delivered_with_engagement": 610,
      "inferred_dropped": 568,
      "mnos_suspected": 1
    }
  }
}

GET /api/v1/analytics/per-route-delivery is the connector-side companion: the same counters grouped by the carrier connector that carried each message (the wholesale softswitch, a per-SMPP credential, or the connector the retry pipeline fell back to), paginated with page / pageSize. totals.degraded covers every route, not just the page.

200

{
  "data": {
    "channel": "sms",
    "window": "7d",
    "buckets": [
      {
        "connector": "devotel-switch",
        "terminal": 48210,
        "delivered": 47122,
        "failed": 811,
        "undelivered": 277,
        "delivery_rate": 97.74,
        "failure_rate": 1.68,
        "undelivered_rate": 0.57
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 },
    "totals": {
      "connectors": 1,
      "terminal": 48210,
      "delivered": 47122,
      "failed": 811,
      "undelivered": 277,
      "degraded": 0
    }
  }
}

GET /api/v1/analytics/route-dlr-anomaly classifies every outbound SMS route (carrier × destination country) against its learned 14-day delivery-rate baseline — drop, normal, or insufficient_data — so a carrier silently degrading one route surfaces before your customers notice. No query parameters.

200

{
  "data": {
    "computed_at": "2026-08-28T10:00:00Z",
    "bucket_day": "2026-08-27T00:00:00Z",
    "baseline_days": 14,
    "routes": [
      {
        "route": "devotel-switch|US",
        "provider": "devotel-switch",
        "country": "US",
        "status": "drop",
        "anomalous": true,
        "currentRate": 0.7821,
        "currentSample": 412,
        "currentDelivered": 322,
        "baselineMean": 0.9533,
        "baselineStddev": 0.0042,
        "effectiveStddev": 0.01,
        "zScore": -17.12,
        "dropPoints": 0.1712,
        "sampleSize": 12
      }
    ],
    "summary": {
      "routes_total": 1,
      "routes_dropping": 1,
      "routes_insufficient_data": 0
    }
  }
}

GET /api/v1/analytics/route-latency-slo catches the two blind spots the DLR-rate detector cannot see: a route that still delivers ~100% but has slowed to minutes (p95 latency against the 300 s SLO), and a route whose DLRs silently stopped arriving (share of sends stuck non-terminal past the receipt grace). Each route lists the thresholds it breached.

200

{
  "data": {
    "computed_at": "2026-08-28T10:00:00Z",
    "window_start": "2026-08-28T04:00:00Z",
    "window_end": "2026-08-28T10:00:00Z",
    "lookback_hours": 6,
    "p95_slo_seconds": 300,
    "silent_ratio_slo": 0.15,
    "routes": [
      {
        "route": "devotel-switch|US",
        "provider": "devotel-switch",
        "country": "US",
        "status": "breach",
        "anomalous": true,
        "latencyBreach": true,
        "silentFailure": false,
        "breaches": ["p95 latency 612s > 300s SLO"],
        "sent": 1812,
        "receiptEligible": 1711,
        "silent": 41,
        "silentRatio": 0.024,
        "deliveredTimed": 1662,
        "p50LatencySeconds": 84,
        "p95LatencySeconds": 612
      }
    ],
    "summary": {
      "routes_total": 1,
      "routes_breaching": 1,
      "routes_insufficient_data": 0
    }
  }
}

Satisfaction goals

Satisfaction goals put a target on one survey metric — CSAT (percent), NPS (points), or CES (score) — and recompute progress from your live survey responses on every read; nothing is stored but the target itself. Every operation in this cluster parses the same goal object: the stored fields plus a progress envelope comparing the live value against your target.

200

{
  "data": {
    "id": "satgoal_5Eb9c2d14",
    "name": "Raise CSAT to 85%",
    "metric": "csat",
    "metric_label": "CSAT",
    "target": 85,
    "survey_id": null,
    "window_days": 30,
    "enabled": true,
    "baseline": 78,
    "unit": "percent",
    "progress": {
      "current": 82.4,
      "target": 85,
      "baseline": 78,
      "unit": "percent",
      "progress_pct": 62.9,
      "attained": false,
      "remaining": 2.6,
      "sample_size": 412
    },
    "created_at": "2026-07-01T09:00:00.000Z",
    "updated_at": "2026-08-01T09:00:00.000Z"
  }
}

current is the live metric value over window_days (null until responses exist), baseline is the value captured when the goal was created, and progress_pct measures the journey from baseline to target, clamped to 0–100; attained flips to true once current reaches the target. The five operations wrap that object:

GET /api/v1/analytics/satisfaction-goals returns { items, total } of the goal object above.
GET /api/v1/analytics/satisfaction-goals/{id} returns the single goal object (404 when the id is not one of yours).
POST /api/v1/analytics/satisfaction-goals creates a goal — body: name, metric (csat | nps | ces), target within the metric’s scale, optional survey_id, window_days (1–365, default 30), enabled — and returns 201 with the goal object; the baseline is captured from live responses at creation.
PATCH /api/v1/analytics/satisfaction-goals/{id} updates any of name, target, survey_id, window_days, enabled (at least one; metric is immutable) and returns 200 with the recomputed goal object.
DELETE /api/v1/analytics/satisfaction-goals/{id} stops tracking the target and returns 200 with:

200

{
  "data": { "id": "satgoal_5Eb9c2d14", "deleted": true }
}

Writes require owner, admin, or developer; reads follow the analytics-read hierarchy. A target outside the metric’s scale (CSAT 0–100, NPS −100–100, CES 0–10) is a 422 VALIDATION_ERROR naming the accepted range. (The conversion-goal cluster — GET /analytics/goals, paged in section 2 — is the separate “which touchpoint drove a sale” surface.)

Portfolio and campaign intelligence

GET /api/v1/analytics/sentiment rolls per-message sentiment up across conversations: a portfolio-wide totals line, a chronological trend, and per-channel / per-agent / per-language / per-resolution breakdowns, each carrying a net sentiment index in −100–100.

200

{
  "data": {
    "window": "7d",
    "granularity": "day",
    "totals": {
      "total": 8432,
      "avg_score": 0.18,
      "positive": 4620,
      "neutral": 2648,
      "negative": 1164,
      "net_sentiment": 41.0
    },
    "trend": [
      {
        "bucket": "2026-08-14T00:00:00Z",
        "total": 1204,
        "avg_score": 0.21,
        "positive": 684,
        "neutral": 361,
        "negative": 159,
        "net_sentiment": 43.6
      }
    ]
  }
}

GET /api/v1/analytics/sms-click-through is the channel-level click-through panel over your tracked short links: sends, tracked sends, raw and verified clicks, and both CTRs per campaign (or per queue with group=queue), paginated like the route breakdown above. click_rate is null for a bucket that carried no tracked links.

200

{
  "data": {
    "channel": "sms",
    "group": "campaign",
    "window": "7d",
    "rows": [
      {
        "bucketKey": "campaign_01J9M4QX",
        "bucketLabel": "August promo blast",
        "sends": 5200,
        "tracked_sends": 5198,
        "sends_with_clicks": 1190,
        "total_clicks": 1744,
        "unique_clickers": 1042,
        "verified_clicks": 1310,
        "click_rate": 0.23,
        "verified_click_rate": 0.25
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 },
    "totals": {
      "buckets": 1,
      "sends": 5200,
      "tracked_sends": 5198,
      "sends_with_clicks": 1190,
      "total_clicks": 1744,
      "unique_clickers": 1042,
      "verified_clicks": 1310,
      "click_rate": 0.23,
      "verified_click_rate": 0.25
    }
  }
}

GET /api/v1/analytics/telegram returns the Telegram-only KPIs the generic rollups cannot express: bot-blocked rate (Bot API 403 user-blocked family), custom-emoji rate, and the DM-vs-group split with a per-chat-type breakdown.

200

{
  "data": {
    "totals": {
      "total_outbound": 12840,
      "bot_blocked_count": 213,
      "bot_blocked_rate": 1.66,
      "custom_emoji_count": 640,
      "custom_emoji_rate": 4.98
    },
    "group_vs_dm": {
      "dm": 9120,
      "non_dm": 3720,
      "by_chat_type": [
        { "chat_type": "private", "message_count": 9120 },
        { "chat_type": "supergroup", "message_count": 2400 },
        { "chat_type": "group", "message_count": 1320 }
      ]
    }
  }
}

GET /api/v1/analytics/topic-intelligence answers “what are customers contacting us about, and is it rising or falling” across voice, SMS, WhatsApp, email, and web chat: up to 50 trending contact reasons with current-vs-prior volume, the per-channel split, CSAT / deflection / handling-time rollups, and linked example threads.

200

{
  "data": {
    "window": "30d",
    "current_since": "2026-07-16T00:00:00Z",
    "previous_since": "2026-06-16T00:00:00Z",
    "total_conversations": 2140,
    "topics": [
      {
        "topic": "billing",
        "volume": 312,
        "previous_volume": 240,
        "change_pct": 30.0,
        "trend": "rising",
        "channels": {
          "voice": 96,
          "sms": 0,
          "whatsapp": 138,
          "email": 54,
          "web_chat": 24
        },
        "avg_csat": 0.72,
        "deflection_rate": 0.41,
        "avg_aht_seconds": 342
      }
    ]
  }
}

GET /api/v1/analytics/usage-anomalies compares the last complete hour of each usage family (SMS throughput and telco cost, voice throughput and telco cost) against a learned 72 h baseline and flags spike or drop — the tenant-wide stall or runaway-cost surge the per-route detectors are too narrow to see.

200

{
  "data": {
    "computed_at": "2026-08-15T12:05:11Z",
    "bucket_start": "2026-08-15T11:00:00Z",
    "baseline_hours": 72,
    "metrics": [
      {
        "metric": "sms_throughput",
        "status": "spike",
        "anomalous": true,
        "current": 9840,
        "baselineMean": 3200.5,
        "baselineStddev": 412.31,
        "effectiveStddev": 412.31,
        "zScore": 16.1,
        "ratio": 3.08,
        "sampleSize": 72
      }
    ],
    "summary": {
      "metrics_total": 4,
      "metrics_anomalous": 1,
      "metrics_insufficient_data": 0
    }
  }
}

Scheduled reports

POST /api/v1/analytics/scheduled-reports/{id}/send-now marks one scheduled report due immediately; the dispatcher emails it on its next tick instead of waiting for the cadence, and the UI polls last_sent_at to show delivery progress. Returns 200 with a queue acknowledgement (404 when the id does not resolve to one of your reports); requires owner or admin and supports the Idempotency-Key header.

200

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

PATCH /api/v1/analytics/scheduled-reports/{id} updates any of name, type, frequency, recipients, filters, enabled, timezone (at least one). Changing frequency re-anchors the cadence from the last send; the derived next tick never lands in the past. Returns 200 with the updated report:

200

{
  "data": {
    "id": "scheduledReport_01J9Z8H2M4C",
    "organization_id": "org_2abc",
    "name": "Weekly deliverability digest",
    "type": "deliverability",
    "frequency": "weekly",
    "recipients": ["ops@acme.example"],
    "filters": null,
    "enabled": true,
    "timezone": "America/New_York",
    "last_sent_at": "2026-08-21T13:00:00Z",
    "next_send_at": "2026-08-28T13:00:00Z",
    "created_by": "user_2abc",
    "created_at": "2026-07-30T09:12:00Z",
    "updated_at": "2026-08-28T09:41:12Z"
  }
}

API Reference

All Endpoints

Worked analytics queries