Skip to content

Analytics with the TypeScript SDK ​

The analytics resource exposes engagement metrics — likes, comments, shares, impressions — both rolled up and per post.

Methods ​

MethodWhat 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 ​

typescript
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 ​

typescript
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:

typescript
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).

typescript
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 ​

typescript
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:

typescript
await socifyr.analytics.sync()

It re-aggregates recent engagement and captures today's follower counts, returning { success, followers: { captured, failed } }.

Next steps ​