Top Posts

GET /v1/latest/{level}/posts/{limit}/{platform}/{region}/{item_id}

Returns the top TikTok posts for a category or a brand, in the same order as the dashboard: average weekly views over the last month, highest first. The identifier in the response is named after the requested level: cat1_id, cat2_id, cat3_id, cat4_id, cat5_id or brand_id.

Parameters

Name	Type	Required	Description
`level`	`string`	yes	Categorisation level, or `brand` for the top posts of a brand. One of `cat1, cat2, cat3, cat4, cat5, brand`.
`limit`	`string`	yes	Number of posts to return. One of `top5, top20, top100, all`.
`platform`	`string`	yes	One of `tiktok`.
`region`	`string`	yes	Region code for the market you want data from. One of `us, gb, fr, kr, jp, global`.
`item_id`	`UUID`	yes	Identifier of the category (`cat1` to `cat5`) or of the brand (`brand`) you want posts for (see Find Category and Find Brand).

Post fields

Name	Description
`rank`	Position in the ranking, starting at 1.
`post_id`	Spate identifier of the post.
`url`	TikTok URL of the post.
`created_at`	Publication date of the post.
`avg_weekly_views`	Average weekly views over the last month. Used for the ranking.
`last_week_views`	Views gained during the last week.
`total_views`	Total views since the post was published.
`total_likes`	Total likes since the post was published.
`last_week_likes`	Likes gained during the last week.
`wow` / `mom`	Week-over-week and month-over-month change in views.
`is_paid`	Paid partnership or brand partner post.
`is_shop`	TikTok Shop post.
`sentiment_score` / `sentiment_summary`	Sentiment of the comments, from 1 (negative) to 10 (positive), with a short summary.
`transcript`	Transcript of the video.

Fields are null when the data is not available, for example transcript for videos with music only. dashboard is null for cat1, which has no category page in the app. Posts with the same views share a position in the dashboard; here each post gets its own rank, so all can return more posts than the last position shown in the app.

Examples

Top 5 posts on TikTok for hair looks in the US

Request

Terminal

curl https://api.spate.nyc/v1/latest/cat3/posts/top5/tiktok/us/276dc485-51c9-4644-8081-34bdc94e762b \
  -H "Authorization: Bearer $SPATE_API_KEY" | jq

Response

{
  "key": "/v1/2026w42/cat3/posts/top5/tiktok/us/276dc485-51c9-4644-8081-34bdc94e762b",
  "credits_used": 60,
  "data": {
    "cat3_id": "276dc485-51c9-4644-8081-34bdc94e762b",
    "dashboard": "https://app.spate.nyc/categoryThree/276dc485-51c9-4644-8081-34bdc94e762b/tiktok?country=US#top-posts",
    "posts": [
      {
        "rank": 1,
        "post_id": "3d300dd9-4677-41b1-95ba-e6acb1170034",
        "url": "https://www.tiktok.com/@MS4wLjABAAAANPSvTzcLEGq3dGMxz96fTWeZWe4zOtxqF0Q5oDWMVt3AGGKK-P3pAV47ek1PB9mh/video/7691472219318275341",
        "created_at": "2026-09-30",
        "avg_weekly_views": 27020256,
        "last_week_views": 15020390,
        "total_views": 54040511,
        "total_likes": 3937039,
        "last_week_likes": 996196,
        "wow": -0.6150603940977015,
        "mom": null,
        "is_paid": false,
        "is_shop": false,
        "sentiment_score": 8,
        "sentiment_summary": "Comments show a mix of amusement and empathy, with users recalling personal experiences, like 'tender headed' pain and familiarity with strict parenting styles.",
        "transcript": null
      },
      ...
    ],
    "call_cost": 10,
    "data_cost": 50
  }
}

Top 5 posts on TikTok for Karseell in the US

Request

Terminal

curl https://api.spate.nyc/v1/latest/brand/posts/top5/tiktok/us/fdadacf9-3373-4e38-b50a-1d89b315115c \
  -H "Authorization: Bearer $SPATE_API_KEY" | jq

Response

{
  "key": "/v1/2026w42/brand/posts/top5/tiktok/us/fdadacf9-3373-4e38-b50a-1d89b315115c",
  "credits_used": 60,
  "data": {
    "brand_id": "fdadacf9-3373-4e38-b50a-1d89b315115c",
    "dashboard": "https://app.spate.nyc/brands/fdadacf9-3373-4e38-b50a-1d89b315115c/tiktok?country=US#top-posts",
    "posts": [
      {
        "rank": 1,
        "post_id": "921ed956-1dd4-4bfd-8628-ac5c20a0823b",
        "url": "https://www.tiktok.com/@MS4wLjABAAAAmRYBX54VqkH8KawAQSXLZ2iFO59siYx4FwtTn9K1sG2-oCsmJbT_Yatm0incpwR-/video/7682722969172397326",
        "created_at": "2026-09-07",
        "avg_weekly_views": 15260351,
        "last_week_views": 847595,
        "total_views": 61990760,
        "total_likes": 994756,
        "last_week_likes": 11477,
        "wow": -0.43740159779950766,
        "mom": -0.10718950530675532,
        "is_paid": false,
        "is_shop": false,
        "sentiment_score": 6,
        "sentiment_summary": "Reactions are mixed, with curiosity about authenticity and some criticism for perceived racial themes; comments like 'I need it' show interest.",
        "transcript": "Bro, what are you doing? Chill out. Just watch. No way where you get that?"
      },
      ...
    ],
    "call_cost": 10,
    "data_cost": 50
  }
}