Copy page

Migration

Migration: Analytics v2 to TimescaleDB

Migration Guide: Analytics v2 to TimescaleDB

This guide helps you migrate from the deprecated Orleans grain-based analytics endpoints (v2) to the new TimescaleDB-backed analytics endpoints (v3).

Overview

The platform is transitioning SMS analytics from an in-memory Orleans grain architecture to a persistent TimescaleDB time-series database. This change provides:

• Improved accuracy: Persistent storage with guaranteed consistency vs. eventual consistency from grain state
• Better performance: TimescaleDB hypertables and continuous aggregates optimized for time-series queries
• Simplified data model: Cleaner response structure focused on SMS metrics (no cost fields)
• Extended history: 12 months of queryable analytics history per tenant

Deprecation Timeline

Phase	Date	Action
Deprecation Notice	2026-01-07	v2 endpoints return Deprecation: true header
Soft Deadline	2026-03-07	Recommended migration completion
Hard Deadline	2026-04-07	v2 endpoints removed

Endpoint Mapping

Daily Analytics

Old (v2):

Code
GET /api/v2/analytics/overview
GET /api/v2/analytics/status-distribution

New (v3):

Code
GET /sms/analytics/daily?startDate=2026-01-01&endDate=2026-01-07

Period Analytics (Weekly/Monthly/Quarterly/Yearly)

Old (v2):

Code
GET /api/v2/analytics/performance?granularity=daily
GET /api/v2/analytics/delivery-trend?granularity=weekly

New (v3):

Code
GET /sms/analytics/period?startDate=2026-01-01&endDate=2026-03-31&granularity=week
GET /sms/analytics/period?startDate=2026-01-01&endDate=2026-03-31&granularity=month
GET /sms/analytics/period?startDate=2026-01-01&endDate=2026-03-31&granularity=quarter
GET /sms/analytics/period?startDate=2026-01-01&endDate=2026-03-31&granularity=year

Request/Response Changes

Daily Analytics Response

Old (v2) Response:

Code
{
  "organizationId": "tenant-123",
  "totalMessagesSentLast30Days": 125340,
  "totalCostLast30Days": 2506.80,
  "deliveryRateLast30Days": 95.64,
  "messagesInLast24Hours": 4215,
  "messagesPendingLast30Days": 2217,
  "messagesFailedLast30Days": 3247
}

New (v3) Response:

Code
{
  "data": [
    {
      "dateUtc": "2026-01-01",
      "tenantId": "tenant-123",
      "direction": "outbound",
      "attemptedCount": 1250,
      "processedCount": 1248,
      "deliveredCount": 1195,
      "failedCount": 53,
      "uniqueRecipientCount": 892,
      "avgSendToFinalStatusSeconds": 3.45,
      "deliveryRatePercent": 95.75,
      "failureRatePercent": 4.25
    }
  ],
  "count": 1
}

Key Differences

Field	v2	v3	Notes
Cost metrics	totalCostLast30Days	❌ Removed	Delegated to external billing API
Time scope	Fixed (24h, 30d)	Flexible date range	Use startDate and endDate query params
Granularity	Per-request	Daily base + period rollups	Use /daily for day-by-day, /period for aggregates
Direction	Not supported	direction field	Defaults to outbound; inbound reserved for future
Latency	Not available	avgSendToFinalStatusSeconds	New metric for delivery performance
Unique recipients	Not available	uniqueRecipientCount	New metric for reach analysis

Authentication

Both v2 and v3 endpoints use the same Zitadel-based authentication. No changes required.

Code
Authorization: Bearer <your-jwt-token>

The tenant ID is extracted from the JWT claims (org_id). Cross-tenant queries are not permitted except for internal/operator roles.

Migration Code Examples

JavaScript/TypeScript

Before (v2):

Code
const response = await fetch('/api/v2/analytics/overview', {
  headers: { 'Authorization': `Bearer ${token}` }
});
const overview = await response.json();
console.log(`Sent: ${overview.totalMessagesSentLast30Days}`);
console.log(`Cost: ${overview.totalCostLast30Days}`); // Will be removed

After (v3):

Code
const today = new Date().toISOString().split('T')[0];
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0];

const response = await fetch(
  `/sms/analytics/daily?startDate=${thirtyDaysAgo}&endDate=${today}`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
const { data } = await response.json();

const totalAttempted = data.reduce((sum, d) => sum + d.attemptedCount, 0);
const avgDeliveryRate = data.reduce((sum, d) => sum + d.deliveryRatePercent, 0) / data.length;

console.log(`Attempted: ${totalAttempted}`);
console.log(`Avg Delivery Rate: ${avgDeliveryRate.toFixed(2)}%`);
// For cost, call the billing API separately

C# / .NET

Before (v2):

Code
var overview = await httpClient.GetFromJsonAsync<AnalyticsOverviewDto>("/api/v2/analytics/overview");
Console.WriteLine($"Sent: {overview.TotalMessagesSentLast30Days}");
Console.WriteLine($"Cost: {overview.TotalCostLast30Days}"); // Will be removed

After (v3):

Code
var startDate = DateOnly.FromDateTime(DateTime.UtcNow.AddDays(-30));
var endDate = DateOnly.FromDateTime(DateTime.UtcNow);

var response = await httpClient.GetFromJsonAsync<DailySmsAnalyticsResponse>(
    $"/sms/analytics/daily?startDate={startDate:yyyy-MM-dd}&endDate={endDate:yyyy-MM-dd}");

var totalAttempted = response.Data.Sum(d => d.AttemptedCount);
var avgDeliveryRate = response.Data.Average(d => d.DeliveryRatePercent ?? 0);

Console.WriteLine($"Attempted: {totalAttempted}");
Console.WriteLine($"Avg Delivery Rate: {avgDeliveryRate:F2}%");
// For cost, call the billing API separately

Billing/Cost Data

Cost analytics have been removed from the SMS Analytics API and are now provided by a separate billing service. If your application requires cost data, please contact support for the billing API documentation.

FAQ

Q: Why are cost fields removed?

A: Billing is now handled by an external service that provides more accurate cost tracking, including discounts, credits, and multi-currency support. This separation improves the maintainability of both systems.

Q: What happens to my historical data?

A: Analytics data is retained for 12 months in TimescaleDB. Data older than 12 months may be archived. Historical data from the old grain-based system is not automatically migrated; the new system accumulates data as new SMS events occur.

Q: Can I query inbound SMS analytics?

A: Not yet. The direction field is included in the response for future compatibility, but currently only outbound analytics are available. Inbound analytics will be added in a future release.

Q: Are the rates computed differently?

A: Rates are computed from the aggregated counts at query time:

• deliveryRatePercent = (deliveredCount / processedCount) * 100
• failureRatePercent = (failedCount / processedCount) * 100

Q: How do I handle the deprecation header?

A: Look for the Deprecation: true response header from v2 endpoints. Log a warning and plan your migration before the Sunset date specified in the response headers.

Code
const response = await fetch('/api/v2/analytics/overview', { ... });
if (response.headers.get('Deprecation') === 'true') {
  console.warn('Analytics v2 is deprecated. Migrate to /sms/analytics/daily');
}

Support

If you encounter issues during migration, please:

1. Check the SMS Analytics API documentation
2. Review the API changelog
3. Contact support at support@tech231.com

---

Last updated: 2026-01-07