Analytics - bundle.social

Everything you need to know about analytics before you read the platform-specific pages. This page covers refresh rates, rate limits, data retention, and why some numbers are zero. For platform-specific metrics and quirks, see each platform’s dedicated page.

Analytics Refresh & Rate Limits

Default Refresh

Analytics are automatically refreshed every 24 hours. You don’t need to run your own refresh job for standard analytics updates.

Force Refresh

You can request analytics to be refreshed immediately by calling the analytics force refresh endpoints.

Target	Endpoint	Body
Social account analytics	`POST /api/v1/analytics/social-account/force`	`{ "teamId": "...", "platformType": "INSTAGRAM" }`
Post analytics	`POST /api/v1/analytics/post/force`	`{ "postId": "...", "platformType": "INSTAGRAM" }`
Imported post analytics	`POST /api/v1/analytics/post/force`	`{ "importedPostId": "..." }`

However, force refresh requests are rate limited to number of teams x 5 per day. Per organization. No exceptions. You may ask why? To protect US from our greatest and brightest vibe code engineers doing:

while (true) {
  await bundlesocial.analytics.analyticsForceRefresh({
    teamId: team.id,
  });
}

We had such cases. We are not joking. Someone actually did this in production.

Rate Limit Formula: Maximum force refresh requests per day = number of teams x 5For example, if you have 10 teams, you can make up to 50 force refresh requests per day. Post analytics have the same limit: teams x 5.If you exceed the limit, the API returns 429 Too Many Requests.

Custom Refresh Periods

By default, analytics are automatically refreshed every 24 hours. However, we can configure custom refresh periods based on your organization’s needs. Important: If you require a higher refresh rate (e.g., every 15 minutes for large organizations), there may be additional charges due to increased data costs. We will discuss these costs with you directly to determine the best solution for your use case.

Data Retention

We retain analytics data for 30 days from the date of creation. After that, it’s gone. Poof. Deleted. If your team needs yearly or long-term history, we recommend fetching and storing the data daily on your end. Build a cron job, pipe it to your database, and sleep well at night. This retention period is fixed and is not extended automatically. Maybe we are evil?

30 days. That’s it. If you need analytics from 3 months ago and you didn’t save them, we can’t help you. We told you. Right here. In this doc. That you’re reading right now.

For the full breakdown of what we retain and for how long (not just analytics), see Data Retention.

Important Note: Data Differences & Zeros

Data shown in our platform may differ from what you see on the social media platform itself. This can happen for several reasons:

Processing Delays: Platforms may take time to process and return analytics data. For example, TikTok can take up to 48 hours for some detailed analytics like audience demographics and splits.
Rolling Window Timing: When platforms return rolling window data, the exact time window and aggregation method may differ slightly from what’s displayed in their native interfaces.
Data Availability: Some metrics may be available in the platform’s native interface but not through their API, or vice versa. APIs and dashboards are built by different teams. At big companies. With different priorities.
Update Frequency: Analytics are updated based on when we fetch data from each platform, which may not match the real-time updates you see in the platform’s own interface.
Zero Values: Some metrics return 0 when the platform API doesn’t provide that specific data point. This doesn’t mean you have zero engagement - it means the data is not available through the API. Each platform page clearly marks which fields return 0 and why.

Understanding Analytics

This is what we return in the standard analytics schema.

Rolling Window

Analytics show aggregated data over a fixed time period (e.g., last 30 days) that updates as time progresses. Each time you view analytics, you see data for the most recent period. Older data falls out of the window as newer data is added.

Lifetime

Analytics show a snapshot of cumulative totals from when the post or profile was created up to the current moment. These values represent the current state and will continue to grow over time. These values usually only increase, unless the platform removes or recalculates engagement.

Raw Analytics Data

In addition to the parsed analytics data described above, raw analytics data is available through dedicated raw endpoints. Raw analytics contain the raw payload we store for the snapshot. Depending on the platform, this can be the original API response, a flat metric object built from platform insights, or a platform payload plus a computed summary. This includes:

Platform-specific metrics that may not be mapped to our standard schema
Additional metadata and context provided by the platform
Detailed breakdowns (e.g., audience demographics, engagement by time period, etc.)
LinkedIn: reaction-type breakdowns (our normalized likes field is a single aggregate; raw payloads retain per-reaction detail where the API provides it)

Raw analytics are useful when you need platform-specific metrics that are not included in the standard analytics format. Raw data structure and fields vary significantly between platforms.

Raw Endpoints

Target	Endpoint	Query
Social account raw analytics	`GET /api/v1/analytics/social-account/raw`	`teamId`, `platformType`
Post raw analytics	`GET /api/v1/analytics/post/raw`	`postId` + `platformType`, or `importedPostId`

GET /api/v1/analytics/social-account/raw?teamId=team_123&platformType=FACEBOOK

GET /api/v1/analytics/post/raw?postId=post_123&platformType=FACEBOOK

GET /api/v1/analytics/post/raw?importedPostId=profile_post_123

Raw responses use the same wrapper shape as parsed analytics, but each item includes a platform-specific raw object. Social account raw responses return socialAccount and items[]; post raw responses return post, optional profilePost, and items[].

{
  "socialAccount": {
    "id": "sa_123",
    "type": "INSTAGRAM",
    "teamId": "team_123"
  },
  "items": [
    {
      "id": "raw_123",
      "socialAccountId": "sa_123",
      "analyticsId": "analytics_123",
      "raw": {
        "platformSpecificPayload": {}
      },
      "forced": false,
      "createdAt": "2026-04-27T10:00:00.000Z",
      "updatedAt": "2026-04-27T10:00:00.000Z",
      "deletedAt": null
    }
  ]
}

For exact raw payload examples, use the platform pages:

Raw Availability By Platform

Platform	Profile raw	Post raw	Typical contents
Instagram	Yes	Yes	Account info, daily totals, demographics, media insights
Facebook	Yes	Yes	Page info, page insights, demographic insights, reaction/video/post insight metrics
LinkedIn	Yes	Yes	Member/org analytics, share statistics, reaction breakdowns where available
TikTok	Yes	Yes	Account metrics, audience splits, video watch and source metrics
YouTube	Yes	Yes	Channel/video statistics, video demographics where available
Threads	Yes	Yes	Profile/media insights returned by Threads
Pinterest	Yes	Yes	User/pin analytics and lifetime metric payloads
Reddit	Limited	Limited	Listing data and engagement fields returned by Reddit
Mastodon	Limited	Limited	Account/status payloads with basic engagement
Bluesky	Limited	Limited	Actor/post payloads and calculated engagement inputs
Google Business	Yes	No post raw	Location info, daily metrics, computed summary
Twitter/X	No	No	Analytics endpoints are not available for X
Discord	No	No	Messaging platform; no analytics API
Slack	No	No	Messaging platform; no analytics API

Raw data is subject to the same 30-day retention as parsed analytics. If you need it long-term, fetch and store it yourself.

BTW, you are a nerd for reading all of this.

Platform Summary Table

A quick reference for what each platform gives us (and what it doesn’t).

Platform	Profile Period	Post Period	Key Limitations
Instagram	Rolling (30d)	Lifetime	Views (Unique) returns 0
Facebook	Rolling (30d)	Lifetime	Profile: likes, comments, post count all return 0
LinkedIn (Personal)	Rolling (30d)	Rolling (30d)	Views, post count, following return 0
LinkedIn (Org)	Rolling (30d)	Rolling (30d)	Post count, following, post views/saves return 0
Twitter/X	N/A	N/A	Not available. Won’t be.
TikTok	Rolling (30d)	Lifetime	Post saves return 0
YouTube	Lifetime	Lifetime	Profile likes, following, post shares return 0
Threads	Rolling	Lifetime	Following returns 0
Pinterest	Rolling (30d)	Mixed	Profile comments, post shares return 0
Reddit	N/A	Lifetime	All profile analytics return 0
Mastodon	Snapshot	Lifetime	Most metrics return 0 - very limited
Bluesky	Snapshot	Lifetime	Most metrics return 0 - impressions are calculated
Discord	N/A	N/A	No analytics
Slack	N/A	N/A	No analytics
Google Business	Rolling (30d)	N/A	Profile/location raw analytics only; post analytics are not returned

Available Metrics Reference

Understanding Return Values

Available: The metric is provided by the platform API and returns real data.
Returns 0: The metric returns 0 because the platform API doesn’t provide this data. This is not a bug. This is the platform being stingy.

Profile Analytics Metrics

Metric	Description
`impressions`	Number of times your profile/content was shown
`impressionsUnique`	Number of unique users who saw your profile/content
`views`	Number of times your profile/page was viewed
`viewsUnique`	Number of unique users who viewed your profile
`likes`	Total likes/reactions received
`comments`	Total comments received
`postCount`	Total number of posts published
`followers`	Current follower count
`following`	Current following count

Post Analytics Metrics

Metric	Description
`impressions`	Number of times the post was shown
`impressionsUnique`	Number of unique users who saw the post
`views`	Number of times the post was viewed (for videos, this is play count)
`viewsUnique`	Number of unique users who viewed the post
`likes`	Total likes/reactions received
`dislikes`	Total dislikes (YouTube, Reddit only)
`comments`	Total comments received
`shares`	Total shares/reposts
`saves`	Total saves/bookmarks

Notes

Rolling Window data refreshes to show the most recent period. Each time you check, you see the current window.
Lifetime data represents cumulative totals from creation to now.
Returns 0 means the platform API doesn’t provide that data. Not a bug. Each platform page documents exactly which fields return 0.
Some platforms have date restrictions (e.g., Threads requires posts after April 2024).
LinkedIn has significant differences between personal and organization account analytics.
Metrics may vary slightly between platforms due to how each defines and tracks engagement.
All analytics (parsed and raw) are deleted after 30 days. See Data Retention.

​Analytics Refresh & Rate Limits

​Default Refresh

​Force Refresh

​Custom Refresh Periods

​Data Retention

​Important Note: Data Differences & Zeros

​Understanding Analytics

​Rolling Window

​Lifetime

​Raw Analytics Data

​Raw Endpoints

​Raw Availability By Platform

​Platform Summary Table

​Available Metrics Reference

​Understanding Return Values

​Profile Analytics Metrics

​Post Analytics Metrics

​Notes

Analytics Refresh & Rate Limits

Default Refresh

Force Refresh

Custom Refresh Periods

Data Retention

Important Note: Data Differences & Zeros

Understanding Analytics

Rolling Window

Lifetime

Raw Analytics Data

Raw Endpoints

Raw Availability By Platform

Platform Summary Table

Available Metrics Reference

Understanding Return Values

Profile Analytics Metrics

Post Analytics Metrics

Notes