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?
| Method | Path | Purpose |
|---|---|---|
GET | /analytics | Workspace totals, trend, per-platform breakdown |
GET | /analytics/top-posts | Best posts by engagement |
GET | /analytics/followers | Follower growth per account |
GET | /analytics/accounts | Account comparison |
GET | /analytics/best-times | Day and hour heatmap |
GET | /analytics/export | CSV of per-post engagement |
GET | /analytics/platform-metrics | Which metrics each platform reports |
GET | /analytics/post/:uploadId | One post across its platforms |
POST | /analytics/sync | Re-aggregate and capture follower counts |
What query parameters do analytics endpoints take?
| Param | Type | Default | Used by | Notes |
|---|---|---|---|---|
period | enum | none | all except platform-metrics, post | last_day, last_week, last_month, last_3months, last_year. Overrides from and to. |
from, to | ISO 8601 | none | same | Ignored when period is set. |
platform | string | all | same | A platform name such as instagram. |
granularity | enum | daily | /analytics | daily, weekly, monthly. |
limit | integer | 10 | /analytics/top-posts | 1 to 50. |
connection | string | all | /analytics/followers, /analytics/accounts | A 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?
curl "https://api.socifyr.com/api/analytics?period=last_month&platform=instagram&granularity=weekly" \
-H "Authorization: Bearer sk_..."{
"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.
curl "https://api.socifyr.com/api/analytics/top-posts?period=last_3months&limit=3" \
-H "Authorization: Bearer sk_..."{
"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.
{
"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).
| Query | Description |
|---|---|
period | last_day · last_week · last_month · last_3months · last_year. Overrides from/to. Default: last 30 days |
from, to | ISO 8601 dates |
connection | Connection slug, e.g. instagram-mybrand |
platform | Platform filter, e.g. x |
{
"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": []
}
]
}
}followersisnulluntil the account's first daily snapshot.changePctisnullwhen there's no non-zero baseline in the window.isTracked: falsemeans 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.
{
"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
}
]
}
}| Field | Meaning |
|---|---|
engagement | likes + comments + shares + saves on posts published in the window |
engagementRate | engagement ÷ impressions, percent |
followerEngagementRate | average 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.
curl "https://api.socifyr.com/api/analytics/export?period=last_month" \
-H "Authorization: Bearer sk_..." \
-o analytics.csvColumns: 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:
{
"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.
{
"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.
{ "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.