Skip to content

Analytics API ​

The Analytics API reports engagement for published posts, follower counts per connected account, and the best times to post. All routes are under /api/analytics, need the analytics.view permission, and are available to guarded API keys, because they only read data (sync only refreshes it).

Auth and workspace selection are in the REST API overview.

Which analytics endpoints can I call? ​

MethodPathPurpose
GET/analyticsWorkspace totals, trend, per-platform breakdown
GET/analytics/top-postsBest posts by engagement
GET/analytics/followersFollower growth per account
GET/analytics/accountsAccount comparison
GET/analytics/best-timesDay and hour heatmap
GET/analytics/exportCSV of per-post engagement
GET/analytics/platform-metricsWhich metrics each platform reports
GET/analytics/post/:uploadIdOne post across its platforms
POST/analytics/syncRe-aggregate and capture follower counts

What query parameters do analytics endpoints take? ​

ParamTypeDefaultUsed byNotes
periodenumnoneall except platform-metrics, postlast_day, last_week, last_month, last_3months, last_year. Overrides from and to.
from, toISO 8601nonesameIgnored when period is set.
platformstringallsameA platform name such as instagram.
granularityenumdaily/analyticsdaily, weekly, monthly.
limitinteger10/analytics/top-posts1 to 50.
connectionstringall/analytics/followers, /analytics/accountsA connection slug such as instagram-mybrand.

Other endpoints reject connection, because unknown query fields return 400.

How do I get workspace analytics with the API? ​

bash
curl "https://api.socifyr.com/api/analytics?period=last_month&platform=instagram&granularity=weekly" \
  -H "Authorization: Bearer sk_..."
json
{
  "success": true,
  "data": {
    "snapshots": [
      {
        "date": "2026-10-19",
        "platform": "instagram",
        "metrics": {
          "postsPublished": 3,
          "postsSucceeded": 3,
          "postsFailed": 0,
          "totalLikes": 240,
          "totalComments": 18,
          "totalShares": 5,
          "totalImpressions": 3500,
          "totalReach": 3100,
          "totalClicks": 0,
          "totalSaves": 12,
          "avgEngagementRate": 7.6
        }
      }
    ],
    "summary": {
      "totalPublished": 12,
      "totalSucceeded": 11,
      "totalFailed": 1,
      "successRate": 92,
      "totalLikes": 940,
      "totalComments": 66,
      "totalShares": 21,
      "totalImpressions": 14000,
      "totalReach": 12100,
      "totalClicks": 40,
      "totalSaves": 55,
      "avgEngagementRate": 6.9
    },
    "previousSummary": { "totalPublished": 9 },
    "platformBreakdown": [
      {
        "platform": "instagram",
        "published": 12,
        "succeeded": 11,
        "failed": 1,
        "totalLikes": 940,
        "totalComments": 66,
        "totalShares": 21,
        "totalImpressions": 14000,
        "totalReach": 12100,
        "totalClicks": 40,
        "totalSaves": 55,
        "avgEngagementRate": 6.9
      }
    ]
  }
}

previousSummary has the same fields as summary, for the window of equal length just before. It is shortened here. successRate is a whole-number percentage.

How do I find my top-performing posts? ​

GET /analytics/top-posts ranks published posts by engagement score (likes + comments + shares + saves, summed over all channels). With no date filter it covers the last 90 days.

bash
curl "https://api.socifyr.com/api/analytics/top-posts?period=last_3months&limit=3" \
  -H "Authorization: Bearer sk_..."
json
{
  "success": true,
  "data": [
    {
      "uploadId": "6a05033584584482ace13d72",
      "title": "We just shipped scheduled posts.",
      "type": "text",
      "platforms": ["linkedin", "x"],
      "publishedAt": "2026-11-13T09:00:04.000Z",
      "metrics": {
        "likes": 120,
        "comments": 14,
        "shares": 9,
        "saves": 3,
        "impressions": 4800,
        "reach": 4100,
        "clicks": 22,
        "engagementScore": 146,
        "engagementRate": 2.98
      }
    }
  ]
}

engagementRate is (likes + comments + shares) divided by impressions, as a percentage, and is 0 when impressions are 0. Posts deleted on the platform are excluded.

When is the best time to post? ​

GET /analytics/best-times buckets published posts by weekday and hour and averages engagement per bucket. It always looks back at least 90 days.

json
{
  "success": true,
  "data": {
    "hasEnoughData": true,
    "totalPosts": 42,
    "cells": [
      { "day": 1, "hour": 14, "posts": 4, "avgEngagement": 87.5 }
    ]
  }
}

day is 0 for Monday through 6 for Sunday. hour is 0 to 23 in UTC. hasEnoughData is false until there are at least 10 posts in the window, so treat early results as noise.

How do I track follower growth per account? ​

Daily follower / subscriber counts per connected account, with the change across the window. Counts are captured once per UTC day (and on POST /analytics/sync).

QueryDescription
periodlast_day · last_week · last_month · last_3months · last_year. Overrides from/to. Default: last 30 days
from, toISO 8601 dates
connectionConnection slug, e.g. instagram-mybrand
platformPlatform filter, e.g. x
json
{
  "success": true,
  "data": {
    "from": "2026-10-12T15:00:00.000Z",
    "to": "2026-11-12T15:00:00.000Z",
    "totals": { "followers": 4200, "change": 180 },
    "accounts": [
      {
        "connectionId": "6a04f715d3d7d93575e65d13",
        "slug": "x-mybrand",
        "platform": "x",
        "username": "@mybrand",
        "isTracked": true,
        "followers": 4200,
        "change": 180,
        "changePct": 4.48,
        "series": [
          { "date": "2026-10-12", "followers": 4020 },
          { "date": "2026-11-12", "followers": 4200 }
        ]
      },
      {
        "connectionId": "6a04f715d3d7d93575e65d14",
        "slug": "linkedin-me",
        "platform": "linkedin",
        "username": "Jane Doe",
        "isTracked": false,
        "followers": null,
        "change": 0,
        "changePct": null,
        "series": []
      }
    ]
  }
}
  • followers is null until the account's first daily snapshot.
  • changePct is null when there's no non-zero baseline in the window.
  • isTracked: false means the platform can't report an audience count with the permissions Socifyr holds.

Tracked platforms: YouTube (subscribers), Facebook Pages, Instagram, Threads, Pinterest, X, Reddit, Bluesky, Mastodon, Telegram (channel members), Tumblr, Hashnode. Not tracked: LinkedIn, TikTok, Discord, Slack, Nostr, Dev.to, Lemmy.

How do I compare accounts side by side? ​

One row per connected account for the window: follower data plus post engagement, sorted by total engagement. Same query parameters as /analytics/followers.

json
{
  "success": true,
  "data": {
    "from": "2026-10-12T15:00:00.000Z",
    "to": "2026-11-12T15:00:00.000Z",
    "accounts": [
      {
        "connectionId": "6a04f715d3d7d93575e65d13",
        "slug": "x-mybrand",
        "platform": "x",
        "username": "@mybrand",
        "isTracked": true,
        "followers": 4200,
        "followerChange": 180,
        "followerChangePct": 4.48,
        "posts": 12,
        "likes": 340,
        "comments": 41,
        "shares": 28,
        "saves": 15,
        "impressions": 21000,
        "engagement": 424,
        "avgEngagementPerPost": 35.33,
        "engagementRate": 2.02,
        "followerEngagementRate": 0.84
      }
    ]
  }
}
FieldMeaning
engagementlikes + comments + shares + saves on posts published in the window
engagementRateengagement ÷ impressions, percent
followerEngagementRateaverage engagement per post ÷ followers, percent; compares accounts of different sizes

How do I export analytics to CSV? ​

GET /analytics/export returns a CSV file (Content-Type: text/csv, filename socifyr-analytics-YYYY-MM-DD.csv), one row per post, up to 1000 rows. It uses the same period, from, to and platform filters. Unlike other routes, the response is raw CSV and is not wrapped in the {success,data} envelope.

bash
curl "https://api.socifyr.com/api/analytics/export?period=last_month" \
  -H "Authorization: Bearer sk_..." \
  -o analytics.csv

Columns: Published At, Title, Type, Platforms, Likes, Comments, Shares, Saves, Impressions, Reach, Clicks, Engagement Rate %.

How do I get analytics for one post? ​

GET /analytics/post/:uploadId accepts the post ID or its requestId. It returns 404 when the post is not in the workspace.

Response:

json
{
  "success": true,
  "data": {
    "uploadId": "...",
    "requestId": "...",
    "title": null,
    "status": "completed",
    "scheduledAt": null,
    "createdAt": "...",
    "platforms": [
      {
        "platform": "instagram",
        "status": "success",
        "postId": "...",
        "postUrl": "...",
        "publishedAt": "...",
        "targetName": "@mybrand",
        "error": null,
        "engagement": {
          "likes": 240,
          "comments": 18,
          "shares": 5,
          "impressions": 3500,
          "clicks": 0,
          "saves": 12
        }
      }
    ]
  }
}

How do I see which metrics each platform reports? ​

GET /analytics/platform-metrics takes no parameters.

json
{
  "success": true,
  "data": [
    {
      "platform": "tiktok",
      "primaryImpression": "views",
      "metrics": ["likes", "comments", "shares", "impressions"],
      "labels": { "impressions": "Video views", "likes": "Hearts" }
    }
  ]
}

How do I trigger an analytics sync? ​

POST /analytics/sync, no body. It re-aggregates the last 30 days of engagement and captures today's follower count for every connected account. This normally runs on its own, once a day. The route is limited to 5 calls per 10 minutes.

json
{ "success": true, "data": { "success": true, "followers": { "captured": 5, "failed": 0 } } }

Frequently asked questions ​

Why is followers null for an account? No daily snapshot exists yet, or the platform cannot report an audience count. Check isTracked.

Why are my engagement numbers zero? Posts on platforms whose insights are unavailable show insightsUnavailable in their channel result from GET /content/:id. See Platforms.

Which timezone do the day and hour buckets use? UTC.

Next steps ​