Read analytics

Analytics works on tracked accounts: Instagram, TikTok and Facebook profiles you add in the dashboard under Analytics → Accounts, or through POST /accounts. Each account is either yours (own) or a competitor’s (competitor).

Note

Analytics is independent from projects: connecting a network to a project doesn’t add the account to analytics.

Start with filters

curl "https://api.warmup.social/analytics/filters?role=own" \
  -H "Authorization: Bearer $WARMUP_TOKEN"

{
  "accounts": [
    { "id": "3b0e…", "platform": "instagram", "username": "acme", "displayName": "Acme", "avatarUrl": "…" }
  ],
  "groups": ["Main brand", "Regional"]
}

Use the ids in accountId and the collection names in group.

Common parameters

Parameter	Default	Description
role	own	own or competitor.
from	30 days before to	Period start, YYYY-MM-DD, inclusive.
to	today in tz	Period end, YYYY-MM-DD, inclusive.
tz	UTC	IANA time zone for day boundaries and posting hours.
platform	all	instagram, tiktok, facebook. Comma-separated or repeated.
group	all	Collection names.
accountId	all	Account ids.

Invalid values fall back to defaults instead of failing: an unknown time zone becomes UTC, swapped dates are swapped back, and periods longer than 365 days are cut from the start. Check period in the response to see what was actually used.

curl "https://api.warmup.social/analytics/overview?from=2026-09-01&to=2026-09-30&tz=Europe/Berlin&platform=instagram,tiktok" \
  -H "Authorization: Bearer $WARMUP_TOKEN"

Reports

Endpoint	Returns
GET /analytics/overview	KPIs with change, a daily series, data freshness.
GET /analytics/platforms	Totals per network.
GET /analytics/top-posts	Best posts; sort = views · er · likes · comments · shares, limit 1–50.
GET /analytics/content	Content types, weekday × hour performance, top 20 hashtags.
GET /analytics/duration	Views by video length bucket and the optimal length.
GET /analytics/activity	Posts per day for the last days (7–365, default 180); ignores from/to.

How metrics are calculated

• Period metrics are the current totals of posts published in [from, to]. Views of an old post gained this month don’t count towards this month.
• Change compares with the previous period of the same length. To be fair to young posts, the previous period is measured at the same post age (comparison.mode: "age_matched"). When comparison.coverage is below 0.8, treat the change as approximate.
• change is in percent; for ER (er) it is in percentage points (changeUnit: "pp"). change is null when there is nothing to compare with.
• available: false means the metric doesn’t exist for the selected networks (for example, saves on Instagram).
• Followers are the sum of the latest known follower counts at the end of each day. Facebook rounds follower counts, so followersApproximate is true when Facebook is in scope.
• Freshness: freshness.stalePosts counts posts whose metrics are older than 48 hours.

Duration buckets

0-15, 15-30, 30-45, 45-60, 60-90, 90-180, 180+ seconds. The optimal bucket is the one with the best average views among buckets with at least 3 posts.