Skip to main content

​
Endpoint

POST https://api.ugc.inc/stats/aggregated/top-posts

​
Overview

Get the top N posts ranked by a specific metric (views, likes, comments, or shares). Uses the latest statistics for each post. Perfect for displaying top content and identifying viral posts.

​
Request Body

​
metric
string
required
The metric to sort by. One of: views, likes, comments, shares
​
limit
number
Number of posts to return. Default: 5. Maximum: 100.
​
postIds
string[]
Array of post IDs to filter. Omit to include all posts.

​
Response

​
data
TopPost[]
Array of top posts sorted by the requested metric
curl -X POST https://api.ugc.inc/stats/aggregated/top-posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "views",
    "limit": 10
  }'

{
  "ok": true,
  "code": 200,
  "message": "Success",
  "data": [
    {
      "post_id": "post_abc123",
      "account_id": "acc_123456",
      "caption": "Amazing workout routine! 💪 #fitness #workout",
      "media_urls": ["https://example.com/video1.mp4"],
      "type": "video",
      "social_id": "7234567890123456789",
      "views": 2500000,
      "likes": 180000,
      "comments": 5600,
      "shares": 12000,
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "post_id": "post_def456",
      "account_id": "acc_789012",
      "caption": "Quick morning stretch routine ☀️",
      "media_urls": ["https://example.com/video2.mp4"],
      "type": "video",
      "social_id": "7234567890987654321",
      "views": 1800000,
      "likes": 120000,
      "comments": 3200,
      "shares": 8500,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}