Skip to content
warmupDocs

Get top posts

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

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

sort
string
default: views
Allowed values: views er likes comments shares

Ranking metric. Invalid values fall back to views.

limit
integer
default: 10 >= 1 <= 50

Number of posts, 1–50.

Responses

Section titled “Responses”

200

Section titled “200”

Best posts of the period.

Media typeapplication/json
object
period
required
object
from
required
string format: date
to
required
string format: date
days
required
integer
sort
required
string
Allowed values: views er likes comments shares
posts
required
Array<object>
object
id
required
string format: uuid
shortcode
string
nullable
url
required

Link to the post on the network.

string format: uri
coverUrl
string
nullable
mediaType
required
string
Allowed values: reel image carousel video slideshow text
caption
required
string
nullable
hashtags
required
Array<string>
publishedAt
required
string format: date-time
durationSeconds
required
number
nullable
metrics
required
object
views
required
integer
nullable
likes
required
integer
nullable
comments
required
integer
nullable
shares
required
integer
nullable
saves
required
integer
nullable
account
required
object
id
required
string format: uuid
platform
required
string
Allowed values: instagram tiktok facebook
username
required
string
avatarUrl
string
nullable
followersCount
integer
nullable
role
required
string
Allowed values: own competitor
er
required

Engagement rate, %.

number
nullable
key
additional properties
any

Example 

{
  "period": {
    "days": 30
  },
  "sort": "views",
  "posts": [
    {
      "mediaType": "reel",
      "account": {
        "platform": "instagram",
        "role": "own"
      }
    }
  ]
}

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"
}