Analytics

PostFuze surfaces two kinds of performance data: post analytics (per-target engagement for a single published post) and account metrics & health (audience size and connection status for a connected account). These endpoints fetch live from each platform on request — they snapshot the result into the post_analytics / account_metrics tables and return the freshly captured numbers. A background job also writes periodic snapshots, which serve as the fallback when a live pull fails or a date range is requested.

Post analytics

GET /posts/{id}/analytics

Fetches live engagement for each published target, snapshots it, and returns the latest snapshot per target plus aggregated totals across every target of the post. Returns 404 if the post does not exist or has been deleted. For a draft or scheduled post — where nothing has been published yet — it returns 422 Unprocessable Entity (“Analytics are only available after a post is published”) rather than empty arrays.

Each entry in metrics_by_account[] is the most recent snapshot for one target:

Metrics are null when a platform does not report that dimension (for example, X does not expose saves for most access tiers). Aggregated totals coerce nulls to zero. Each metrics_by_account[] row maps to a target on the post, so you can join it back to targets[].id for the live permalink and status.

curl https://api.postfuze.com/api/v1/posts/p1a2b3c4-0000-4a9f-9b1c-2e7d6f0a1234/analytics \
  -H "Authorization: Bearer sk_live_…"

{
  "post_id": "p1a2b3c4-0000-4a9f-9b1c-2e7d6f0a1234",
  "metrics_by_account": [
    {
      "target_id": "t_0001",
      "platform": "x",
      "impressions": 12480,
      "reach": 9820,
      "likes": 421,
      "comments": 38,
      "shares": 57,
      "saves": null,
      "clicks": 304,
      "video_views": 0,
      "engagement_rate": 0.041,
      "captured_at": "2026-06-10T18:00:00.000Z"
    },
    {
      "target_id": "t_0002",
      "platform": "instagram",
      "impressions": 30410,
      "reach": 24890,
      "likes": 1894,
      "comments": 132,
      "shares": 410,
      "saves": 765,
      "clicks": 0,
      "video_views": 18220,
      "engagement_rate": 0.102,
      "captured_at": "2026-06-10T18:00:00.000Z"
    }
  ],
  "aggregated_metrics": {
    "total_impressions": 42890,
    "total_reach": 34710,
    "total_likes": 2315,
    "total_comments": 170,
    "total_shares": 467,
    "total_saves": 765,
    "total_clicks": 304,
    "total_video_views": 18220
  }
}

What's available per platform

Snapshots store a common set of columns, but which dimensions a platform actually reports varies. The matrix below is a guide — any dimension a platform omits is returned as null. The raw, unmapped platform payload is retained server-side for each snapshot, so new dimensions can be surfaced without a migration.

Account metrics

GET /social-accounts/{id}/metrics

With no date range, prefers a live pull from the platform (source: "live") and falls back to the most recent stored snapshot (source: "snapshot") when the platform is unreachable. If nothing exists either, the response is { social_account_id, metrics: null, message }. Pass since/until (unix seconds or ISO 8601) to get a data array of stored snapshots over the window instead — see Social Accounts for the ranged shape.

curl https://api.postfuze.com/api/v1/social-accounts/a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234/metrics \
  -H "Authorization: Bearer sk_live_…"

{
  "social_account_id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
  "network": "instagram",
  "source": "live",
  "captured_at": "2026-06-14T12:10:00.000Z",
  "followers": 48210,
  "following": 312,
  "posts_count": 1893,
  "raw": { "period": "day" }
}

{
  "social_account_id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
  "metrics": null,
  "message": "No metrics have been collected for this account yet."
}

Account health

GET /social-accounts/{id}/health

A connection check. When the platform adapter supports it and the account isn’t disabled/revoked, it runs a live probe (refreshing the token if near expiry, then a lightweight identity call) so a hard 401 is caught even when the stored status looks fine; checked_live reports whether that probe ran. Otherwise it falls back to a status + token-expiry check. A refresh failure during the probe flips the account to token_expired (and fires account.token_expired). Returns 404 if the account does not exist or has been deleted.

curl https://api.postfuze.com/api/v1/social-accounts/a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234/health \
  -H "Authorization: Bearer sk_live_…"

{
  "id": "a1b2c3d4-0000-4a9f-9b1c-2e7d6f0a1234",
  "network": "instagram",
  "healthy": true,
  "status": "active",
  "error_code": null,
  "token_expires_at": "2026-08-08T06:00:00.000Z",
  "checked_live": true,
  "checked_at": "2026-06-14T12:30:00.000Z"
}

Availability & latency

These endpoints fetch live on request and snapshot the result. A background job also writes periodic rows to post_analytics / account_metrics, which back the snapshot fallback (and the account-metrics date-range series).

For programmatic reactions to publishing outcomes (rather than polling analytics), subscribe to webhooks such as post.published. See the per-platform guides for which insights each network exposes.