Skip to main content

Analytics Service — API Contracts

Status: populated Owner: Platform Engineering Last updated: 2026-04-18 Companion: APPLICATION_LOGIC

Overview​

All endpoints are internal only — no Kong route. Accessed by admin-dashboard and customer-portal over the cluster network. Auth: mTLS (service mesh) or internal-network trust (not public-facing). Base URL: http://analytics-service.svc.cluster.local:3030

GET /v1/internal/analytics/summary​

Platform-wide summary for the admin dashboard.

Query params:

  • ?from=<ISO8601> — start of window (default: today 00:00 UTC)
  • ?to=<ISO8601> — end of window (default: now)
  • ?granularity=hourly|daily — default daily

Response 200:

{
  "window": { "from": "2026-04-18T00:00:00Z", "to": "2026-04-18T23:59:59Z" },
  "totalMessages": 4821003,
  "deliveredMessages": 4723782,
  "failedMessages": 62419,
  "pendingMessages": 34802,
  "deliveryRate": 0.9797,
  "totalCost": "31250.420000",
  "activeAccounts": 312,
  "peakTps": 2847,
  "avgLatencyMs": 1240,
  "p95LatencyMs": 3200
}

GET /v1/internal/analytics/operators/:id/performance​

Per-operator performance metrics.

Query params: same from, to, granularity.

Response 200:

{
  "operatorId": "018f1a2b-...",
  "window": { "from": "...", "to": "..." },
  "totalMessages": 1204823,
  "deliveredMessages": 1183012,
  "failedMessages": 12004,
  "deliveryRate": 0.9819,
  "avgLatencyMs": 1100,
  "p95LatencyMs": 2800,
  "errorRate": 0.0100,
  "peakTps": 1203,
  "totalCost": "7830.940000"
}

Errors: 404 if operatorId not known to analytics (no data).

GET /v1/internal/analytics/accounts/:id/usage​

Per-account usage breakdown. Used by customer-portal to display usage to customers.

Query params: from, to, granularity. Scope limited to the authenticated account.

Response 200:

{
  "accountId": "acct_...",
  "window": { "from": "...", "to": "..." },
  "messagesSent": 28401,
  "messagesDelivered": 27830,
  "messagesFailed": 380,
  "deliveryRate": 0.9800,
  "totalCost": "184.610000",
  "avgCostPerMessage": "0.006500",
  "segments": 29012,
  "dailyBreakdown": [
    { "date": "2026-04-18", "sent": 4210, "delivered": 4130, "failed": 50, "cost": "27.370000" }
  ]
}

GET /v1/internal/analytics/throughput​

Platform throughput time series — used for the admin real-time throughput chart.

Query params:

  • ?from=<ISO8601>, ?to=<ISO8601>
  • ?resolution=1m|5m|1h — default 5m (minute-granularity is derived from hourly bucketed data with interpolation)

Response 200:

{
  "resolution": "5m",
  "series": [
    { "at": "2026-04-18T10:00:00Z", "tps": 1204, "messages": 36120 },
    { "at": "2026-04-18T10:05:00Z", "tps": 1389, "messages": 41670 }
  ]
}

GET /v1/internal/analytics/delivery-breakdown​

Platform-wide delivery status breakdown by operator and status — used for the admin pie/donut chart.

Query params: from, to.

Response 200:

{
  "window": { "from": "...", "to": "..." },
  "byStatus": {
    "DELIVERED": 4723782,
    "FAILED": 62419,
    "PENDING": 34802,
    "UNDELIVERABLE": 8200
  },
  "byOperator": [
    { "operatorId": "018f1a2b-...", "name": "Carrier Alpha UK", "delivered": 1183012, "failed": 12004, "deliveryRate": 0.9819 }
  ]
}

GET /health/live, GET /health/ready, GET /metrics​

Operational; internal only.

Error Response Shape​

{
  "type": "https://errors.ghasi.io/analytics/INVALID_WINDOW",
  "title": "Invalid time window",
  "status": 400,
  "code": "INVALID_WINDOW",
  "detail": "'from' must be before 'to' and window must be ≤ 90 days",
  "instance": "/v1/internal/analytics/summary"
}