Get Top Posts By Views

Retrieves your top-performing posts ranked by views within a specified date range

Retrieves your top-performing posts ranked by views within a specified date range.

Request Parameters

Parameter	Type	Description	Required
start_date	String	Start date in MM/DD/YYYY format	Yes
end_date	String	End date in MM/DD/YYYY format	Yes
limit	Integer	Limit the number of results. Default is 4. Recommended is 20. Set to 10,000 to get all data.	No
page	Integer	Page number for pagination. Default is 1.	No
per_page	Integer	Number of results per page. Default is 40. Maximum is 100.	No
include_gmv	Boolean	Include GMV (Gross Merchandise Value) data for each post. Default is false.	No

Response Fields

Field	Description
id	Unique identifier for the post
title	Post title or caption
share_url	Direct URL to the post
platform	Social media platform (e.g., “tik_tok”, “instagram”, “youtube”)
content_type	Type of content (e.g., “video”, “image”)
external_id	External platform identifier for the post
username	Username of the creator
name	Display name of the creator
profile_share_url	URL to the creator’s profile
metrics	Object containing engagement metrics (views, likes, comments, shares)
gmv	Gross Merchandise Value for the post (only included when include_gmv=true)

Request Example

curl -X GET "https://api.growi.io/api/public/v1/stats/top_posts_by_views?start_date=01/01/2023&end_date=01/31/2023&limit=5&page=1&per_page=20&include_gmv=true" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \
     -H "Content-Type: application/json"

Response Example

{
  "success": true,
  "data": {
    "top_posts_by_views": [
      {
        "id": 100001,
        "title": "Latest tech trends for 2024! 🚀\n\nJoin our tech community discord in bio for exclusive updates 📱\n\nFollow for daily tech insights and reviews ✅\n\n#tech #gadgets #innovation #technology #technews #review #smartphone #ai #artificialintelligence #future",
        "share_url": "https://www.instagram.com/p/ABC123xyz/",
        "platform": "instagram",
        "content_type": "image",
        "external_id": "ABC123xyz",
        "username": "tech.trends",
        "name": "Tech Trends",
        "profile_share_url": "https://www.instagram.com/tech.trends",
        "metrics": {
          "views": 365558,
          "likes": 12460,
          "comments": 37,
          "shares": 5970
        }
      },
      {
        "id": 100002,
        "title": "Breaking: Major tech company announces revolutionary AI breakthrough in sustainable energy solutions.\n\nResearchers have developed an AI system that optimizes energy consumption, potentially reducing costs by up to 40%.\n\nThis development marks a significant step forward in combining artificial intelligence with environmental sustainability.\n\nJoin our tech community discord in bio for detailed analysis 📱\n\nFollow for daily tech updates ✅\n\n#technology #ai #sustainability #innovation #energy #future",
        "share_url": "https://www.instagram.com/p/DEF456uvw/",
        "platform": "instagram",
        "content_type": "image",
        "external_id": "DEF456uvw",
        "username": "future.tech",
        "name": "Future Tech",
        "profile_share_url": "https://www.instagram.com/future.tech",
        "metrics": {
          "views": 314195,
          "likes": 6165,
          "comments": 123,
          "shares": 3348
        }
      },
      {
        "id": 100003,
        "title": "The evolution of smartphones #viral #tech #smartphone #innovation #future #trending #technology #gadgets #review",
        "share_url": "https://www.tiktok.com/@tech.trends/video/123456789",
        "platform": "tik_tok",
        "content_type": "video",
        "external_id": "123456789",
        "username": "tech.trends",
        "name": "Tech Trends",
        "profile_share_url": "https://www.tiktok.com/@tech.trends",
        "metrics": {
          "views": 216222,
          "likes": 4695,
          "comments": 85,
          "shares": 216
        },
        "gmv": "$2,145.89"
      },
      {
        "id": 100004,
        "title": "Industry experts predict a major shift in consumer technology trends for 2024, with AI-powered personal assistants leading the way.\n\nNew research suggests that 75% of households will have smart home devices by 2025.\n\nThis transformation is reshaping how we interact with technology in our daily lives.\n\nJoin our tech community discord in bio for insights 📱\n\nFollow for daily tech updates ✅\n\n#technology #ai #smarthome #innovation #future #tech",
        "share_url": "https://www.instagram.com/p/GHI789klm/",
        "platform": "instagram",
        "content_type": "image",
        "external_id": "GHI789klm",
        "username": "tech.daily",
        "name": "Tech Daily",
        "profile_share_url": "https://www.instagram.com/tech.daily",
        "metrics": {
          "views": 195485,
          "likes": 2058,
          "comments": 37,
          "shares": 263
        }
      }
    ]
  },
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "row_count": 342,
    "page_count": 18,
    "has_more": true
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

start_date · string<date> · default: 10/01/2025 · required

Start date in MM/DD/YYYY format

end_date · string<date> · default: 11/14/2025 · required

End date in MM/DD/YYYY format

limit · integer · default: 4

Limit the number of results. Default is 4. Recommended is 20. Set to 10,000 to get all data.

include_gmv · boolean · default: false

Include GMV (Gross Merchandise Value) data for each post. Default is false.

Response

200

application/json

Top posts by views retrieved successfully

success · boolean

Example:

true

data · object

Show child attributes