API Reference

Analytics API

Retrieve delivery analytics data programmatically to build custom dashboards, integrate with BI tools, or monitor delivery health in your own systems.

Overview Metrics

GET/api/analytics/overview

GET /api/analytics/overview?from=2026-03-01&to=2026-04-01&site_id=site_abc123
Authorization: Bearer <token>

// Query params:
// from        — ISO 8601 date (default: 30 days ago)
// to          — ISO 8601 date (default: now)
// site_id     — Filter to a specific site (optional)

// Response
{
  "period": { "from": "2026-03-01", "to": "2026-04-01" },
  "totals": {
    "deliveries": 847,
    "successful": 831,
    "failed": 16,
    "retried": 44,
    "success_rate": 98.1,
    "avg_delivery_ms": 1240,
    "posts_published": 72
  },
  "sites": [
    { "id": "site_abc", "name": "Tech Blog", "deliveries": 412, "success_rate": 99.3 },
    { "id": "site_def", "name": "Agency Site", "deliveries": 435, "success_rate": 97.0 }
  ]
}

Delivery Time Series

GET/api/analytics/deliveries

GET /api/analytics/deliveries?granularity=day&from=2026-03-01&to=2026-04-01&site_id=site_abc123
Authorization: Bearer <token>

// granularity: hour | day | week | month

// Response
{
  "granularity": "day",
  "site_id": "site_abc123",
  "data": [
    { "date": "2026-03-01", "delivered": 28, "failed": 1, "retried": 3, "avg_ms": 1100 },
    { "date": "2026-03-02", "delivered": 32, "failed": 0, "retried": 0, "avg_ms": 980 },
    { "date": "2026-03-03", "delivered": 18, "failed": 2, "retried": 5, "avg_ms": 1450 }
  ]
}

Post Delivery History

GET/api/analytics/posts/:id/deliveries

GET /api/analytics/posts/post_xyz789/deliveries
Authorization: Bearer <token>

// Response
{
  "post_id": "post_xyz789",
  "post_title": "My Blog Post",
  "deliveries": [
    {
      "site_id": "site_abc123",
      "site_name": "Tech Blog",
      "status": "delivered",
      "attempts": 1,
      "delivered_at": "2026-04-02T09:01:14Z",
      "response_code": 200,
      "response_time_ms": 834
    },
    {
      "site_id": "site_def456",
      "site_name": "Agency Site",
      "status": "delivered_retry",
      "attempts": 2,
      "delivered_at": "2026-04-02T09:02:45Z",
      "response_code": 200,
      "history": [
        { "attempt": 1, "at": "2026-04-02T09:01:12Z", "code": 503, "error": "Service Unavailable" },
        { "attempt": 2, "at": "2026-04-02T09:01:42Z", "code": 200 }
      ]
    }
  ]
}

Failed Deliveries

GET/api/analytics/failures

GET /api/analytics/failures?from=2026-03-01&site_id=site_abc123
Authorization: Bearer <token>

// Response
{
  "failures": [
    {
      "post_id": "post_xyz789",
      "post_title": "My Post",
      "site_id": "site_abc123",
      "failed_at": "2026-04-01T09:05:00Z",
      "attempts": 3,
      "last_error": "Connection timeout after 30s",
      "last_response_code": null,
      "can_retry": true
    }
  ]
}

Manual Retry

POST/api/analytics/posts/:id/retry

POST /api/analytics/posts/post_xyz789/retry
Authorization: Bearer <token>

{
  "site_id": "site_abc123"  // optional: retry for specific site only
}

// Response
{
  "job_id": "retry_job_456",
  "status": "queued",
  "message": "Retry delivery queued — check analytics in 60 seconds"
}