Get Top Posts By Views

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

GET /stats/top_posts_by_views

cURL

cURL

curl --request GET \
  --url https://api.growi.io/api/public/v1/stats/top_posts_by_views \
  --header 'Authorization: Bearer <token>'

200

{
  "success": true,
  "data": {
    "top_posts_by_views": [
      {
        "id": 100001,
        "title": "Latest tech trends for 2024!",
        "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
        },
        "gmv": "$1,284.53"
      }
    ]
  }
}

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. Defines the metrics-delta window (the period over which view/like/comment/share gains are summed for ranking).	Yes
end_date	String	End date in MM/DD/YYYY format. Defines the metrics-delta window (the period over which view/like/comment/share gains are summed for ranking).	Yes
posted_at_start_date	String	Start date in MM/DD/YYYY format. Restricts the ranked post set to posts created on or after this date (based on posted_at). Must be supplied together with posted_at_end_date.	No
posted_at_end_date	String	End date in MM/DD/YYYY format. Restricts the ranked post set to posts created on or before this date (based on posted_at). Must be supplied together with posted_at_start_date.	No
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

start_date / end_date define the window over which view/like/comment/share deltas are summed (the ranking metric). posted_at_start_date / posted_at_end_date restrict the candidate post set by post creation time before ranking. Both posted_at_* bounds must be supplied together; supplying only one returns an error. When neither is provided, behavior is unchanged.

Example

?start_date=10/01/2025&end_date=11/14/2025
 &posted_at_start_date=10/15/2025&posted_at_end_date=11/01/2025

Returns top posts created Oct 15 – Nov 1, 2025, ranked by their view delta Oct 1 – Nov 14, 2025.

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. Defines the metrics-delta window (period over which view/like/comment/share gains are summed for ranking).

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

End date in MM/DD/YYYY format. Defines the metrics-delta window (period over which view/like/comment/share gains are summed for ranking).

posted_at_start_date · string<date>

Start date in MM/DD/YYYY format. Restricts the ranked post set to posts created on or after this date (based on posted_at). Must be supplied together with posted_at_end_date.

posted_at_end_date · string<date>

End date in MM/DD/YYYY format. Restricts the ranked post set to posts created on or before this date (based on posted_at). Must be supplied together with posted_at_start_date.

limit · integer · default: 4

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

page · integer · default: 1

Page number for pagination. Default is 1.

per_page · integer · default: 40

Number of results per page. Default is 40. Maximum is 100.

Required range: x <= 100

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