Skip to content
warmupDocs

Get analytics overview

GET
/analytics/overview
curl --request GET \
  --url 'https://api.warmup.social/analytics/overview?role=own&from=2026-09-01&to=2026-09-30&tz=UTC' \
  --header 'Authorization: Bearer <token>'

Key metrics for the period with the change against the previous period of the same length, plus a daily series. Period metrics are the current totals of posts published in [from, to].

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
role
string
Allowed values: own competitor

Whose accounts to analyze — your own or competitors.

from
string format: date

Example 

2026-09-01

Period start, YYYY-MM-DD, inclusive. Defaults to 30 days before to. Periods longer than 365 days are cut from the start.

to
string format: date

Example 

2026-09-30

Period end, YYYY-MM-DD, inclusive. Defaults to today in tz.

tz
string
default: UTC

Example 

Europe/Berlin

IANA time zone used to split days.

platform
Array<string>
Allowed values: instagram tiktok facebook

Only these networks. Comma-separated or repeated.

group
Array<string>

Only accounts from these collections (names from “List analytics filters”).

accountId
Array<string>

Only these accounts (ids from “List analytics filters”).

Responses

Section titled “Responses”

200

Section titled “200”

KPIs, daily series and data freshness.

Media typeapplication/json
object
period
required
object
from
required
string format: date
to
required
string format: date
days
required
integer
previousPeriod
required
object
from
required
string format: date
to
required
string format: date
days
required
integer
kpis
required
object
views
required
object
value
required
number
nullable
previous
required
number
nullable
change
required

Change against the previous period; null when there is nothing to compare with.

number
nullable
changeUnit
required

pct — relative change in %, pp — difference in percentage points (ER).

string
Allowed values: pct pp
available
required

false — the metric has no data for this scope (e.g. saves on Instagram).

boolean
posts
required
object
value
required
number
nullable
previous
required
number
nullable
change
required

Change against the previous period; null when there is nothing to compare with.

number
nullable
changeUnit
required

pct — relative change in %, pp — difference in percentage points (ER).

string
Allowed values: pct pp
available
required

false — the metric has no data for this scope (e.g. saves on Instagram).

boolean
er
required
object
value
required
number
nullable
previous
required
number
nullable
change
required

Change against the previous period; null when there is nothing to compare with.

number
nullable
changeUnit
required

pct — relative change in %, pp — difference in percentage points (ER).

string
Allowed values: pct pp
available
required

false — the metric has no data for this scope (e.g. saves on Instagram).

boolean
likes
required
object
value
required
number
nullable
previous
required
number
nullable
change
required

Change against the previous period; null when there is nothing to compare with.

number
nullable
changeUnit
required

pct — relative change in %, pp — difference in percentage points (ER).

string
Allowed values: pct pp
available
required

false — the metric has no data for this scope (e.g. saves on Instagram).

boolean
comments
required
object
value
required
number
nullable
previous
required
number
nullable
change
required

Change against the previous period; null when there is nothing to compare with.

number
nullable
changeUnit
required

pct — relative change in %, pp — difference in percentage points (ER).

string
Allowed values: pct pp
available
required

false — the metric has no data for this scope (e.g. saves on Instagram).

boolean
shares
required
object
value
required
number
nullable
previous
required
number
nullable
change
required

Change against the previous period; null when there is nothing to compare with.

number
nullable
changeUnit
required

pct — relative change in %, pp — difference in percentage points (ER).

string
Allowed values: pct pp
available
required

false — the metric has no data for this scope (e.g. saves on Instagram).

boolean
saves
required
object
value
required
number
nullable
previous
required
number
nullable
change
required

Change against the previous period; null when there is nothing to compare with.

number
nullable
changeUnit
required

pct — relative change in %, pp — difference in percentage points (ER).

string
Allowed values: pct pp
available
required

false — the metric has no data for this scope (e.g. saves on Instagram).

boolean
avgViewsPerDay
required
object
value
required
number
nullable
previous
required
number
nullable
change
required

Change against the previous period; null when there is nothing to compare with.

number
nullable
changeUnit
required

pct — relative change in %, pp — difference in percentage points (ER).

string
Allowed values: pct pp
available
required

false — the metric has no data for this scope (e.g. saves on Instagram).

boolean
followers
required
object
value
required
number
nullable
previous
required
number
nullable
change
required

Change against the previous period; null when there is nothing to compare with.

number
nullable
changeUnit
required

pct — relative change in %, pp — difference in percentage points (ER).

string
Allowed values: pct pp
available
required

false — the metric has no data for this scope (e.g. saves on Instagram).

boolean
daily
required
Array<object>
object
date
required
string format: date
posts
required
integer
views
required
integer
likes
required
integer
comments
required
integer
shares
required
integer
saves
required
integer
followers
required

Total followers at the end of the day; null while there is no data yet.

integer
nullable
followersApproximate
required

true when Facebook is in scope: the network rounds follower counts.

boolean
comparison
required

How the previous period was measured. age_matched — previous-period posts are taken at the same age the current posts have now.

object
mode
required
string
Allowed values: age_matched
asOf
required
string format: date-time
coverage
required

Share of previous-period posts with a snapshot at asOf; below 0.8 the comparison is approximate.

number
nullable
freshness
required
object
posts
required
integer
stalePosts
required

Posts whose metrics were refreshed more than 48 hours ago.

integer
oldestMetricsAt
required
string format: date-time
nullable

Example 

{
  "period": {
    "days": 30
  },
  "previousPeriod": {
    "days": 30
  },
  "kpis": {
    "views": {
      "changeUnit": "pct"
    },
    "posts": {
      "changeUnit": "pct"
    },
    "er": {
      "changeUnit": "pct"
    },
    "likes": {
      "changeUnit": "pct"
    },
    "comments": {
      "changeUnit": "pct"
    },
    "shares": {
      "changeUnit": "pct"
    },
    "saves": {
      "changeUnit": "pct"
    },
    "avgViewsPerDay": {
      "changeUnit": "pct"
    },
    "followers": {
      "changeUnit": "pct"
    }
  },
  "comparison": {
    "mode": "age_matched"
  }
}

401

Section titled “401”

The Bearer token is missing or invalid.

Media typeapplication/json
object
statusCode
required
integer
message
required
One of:
string
error
string
key
additional properties
any

Example 

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}