Analytics with the TypeScript SDK
The analytics resource exposes engagement metrics — likes, comments, shares, impressions — both rolled up and per post.
Methods
| Method | What it does |
|---|---|
get(query?) | Workspace-wide metrics, optionally filtered by date / platform |
getPost(uploadId) | Per-platform breakdown for one post |
getPlatformMetrics() | Metadata about what each platform measures |
followers(query?) | Follower growth per connected account |
accounts(query?) | Side-by-side account comparison (followers, posts, engagement) |
sync() | Re-aggregate metrics and capture today's follower counts |
Workspace analytics
const stats = await socifyr.analytics.get({
from: '2026-01-01',
to: '2026-04-01',
platform: 'instagram', // optional filter
granularity: 'daily', // 'daily' | 'weekly' | 'monthly'
})
console.log(stats.summary)
// {
// totalPublished: 47,
// totalSucceeded: 45,
// totalFailed: 2,
// successRate: 95.74,
// totalLikes: 12_540,
// totalComments: 891,
// totalShares: 230,
// totalImpressions: 245_120,
// avgEngagementRate: 4.2,
// }
for (const point of stats.snapshots) {
console.log(point.date, point.metrics.totalLikes, point.metrics.totalImpressions)
}Per-post analytics
const post = await socifyr.analytics.getPost(uploadId)
// {
// uploadId, requestId, title, status, scheduledAt, createdAt,
// platforms: [
// {
// platform: 'instagram',
// status: 'success',
// postUrl: 'https://instagram.com/p/...',
// publishedAt: '...',
// engagement: {
// likes: 240, comments: 18, shares: 5,
// impressions: 3_500, clicks: 0, saves: 12,
// },
// },
// // ...
// ],
// }Platform metrics schema
Each platform exposes a different set of metrics. Use getPlatformMetrics() to learn what each one tracks:
const platforms = await socifyr.analytics.getPlatformMetrics()
// [
// {
// platform: 'tiktok',
// primaryImpression: 'views',
// metrics: ['likes', 'comments', 'shares', 'impressions'],
// labels: { impressions: 'Video views', likes: 'Hearts' },
// },
// // ...
// ]Follower growth
Follower / subscriber counts are captured once per UTC day for every connected account on a platform that reports them (YouTube, Facebook, Instagram, Threads, Pinterest, X, Reddit, Bluesky, Mastodon, Telegram, Tumblr, Hashnode).
const { totals, accounts } = await socifyr.analytics.followers({ period: 'last_3months' })
console.log(`${totals.followers} followers (${totals.change >= 0 ? '+' : ''}${totals.change})`)
for (const a of accounts) {
if (!a.isTracked) continue // e.g. LinkedIn, TikTok
console.log(a.slug, a.followers, a.change, a.changePct)
// a.series → [{ date: '2026-10-12', followers: 4020 }, ...]
}Filter to one account with connection: 'instagram-mybrand' or one platform with platform: 'x'. Without a period the window is the last 30 days.
Comparing accounts
const { accounts } = await socifyr.analytics.accounts({ period: 'last_month' })
console.table(
accounts.map((a) => ({
account: a.slug,
followers: a.followers,
posts: a.posts,
engagement: a.engagement,
perPost: a.avgEngagementPerPost,
rate: `${a.engagementRate}%`,
perFollower: a.followerEngagementRate === null ? '—' : `${a.followerEngagementRate}%`,
})),
)Rows are sorted by total engagement. followerEngagementRate (average engagement per post ÷ followers) is the fairest way to compare a large account with a small one.
Manual sync
Engagement metrics are fetched by a job that runs every 6 hours, and the analytics aggregation and follower snapshots run once every 24 hours. To force a refresh:
await socifyr.analytics.sync()It re-aggregates recent engagement and captures today's follower counts, returning { success, followers: { captured, failed } }.