> ## Documentation Index > Fetch the complete documentation index at: https://growi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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 ```bash theme={null} 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 ```json theme={null} { "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 } } ``` ## OpenAPI ````yaml GET /stats/top_posts_by_views openapi: 3.0.1 info: title: Growi API description: >- API documentation for Growi platform, showcasing the public tracking event endpoint license: name: MIT version: 1.0.0 servers: - url: https://api.growi.io/api/public/v1 security: - bearerAuth: [] paths: /stats/top_posts_by_views: get: description: >- Retrieves your top-performing posts ranked by views within a specified date range parameters: - name: start_date in: query required: true example: 10/01/2025 schema: type: string format: date default: 10/01/2025 description: >- Start date in MM/DD/YYYY format. Defines the metrics-delta window (period over which view/like/comment/share gains are summed for ranking). - name: end_date in: query required: true example: 11/14/2025 schema: type: string format: date default: 11/14/2025 description: >- End date in MM/DD/YYYY format. Defines the metrics-delta window (period over which view/like/comment/share gains are summed for ranking). - name: posted_at_start_date in: query required: false example: 10/15/2025 schema: type: string format: date description: >- 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. - name: posted_at_end_date in: query required: false example: 11/01/2025 schema: type: string format: date description: >- 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. - name: limit in: query required: false example: 4 schema: type: integer default: 4 description: >- Limit the number of results. Default is 4. Recommended is 20. Set to 10,000 to get all data. - name: page in: query required: false example: 1 schema: type: integer default: 1 description: Page number for pagination. Default is 1. - name: per_page in: query required: false example: 40 schema: type: integer default: 40 maximum: 100 description: Number of results per page. Default is 40. Maximum is 100. - name: include_gmv in: query required: false example: true schema: type: boolean default: false description: >- Include GMV (Gross Merchandise Value) data for each post. Default is false. responses: '200': description: Top posts by views retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: top_posts_by_views: type: array items: type: object properties: id: type: integer example: 100001 description: Unique identifier for the post title: type: string example: Latest tech trends for 2024! description: Post title or caption share_url: type: string example: https://www.instagram.com/p/ABC123xyz/ description: Direct URL to the post platform: type: string example: instagram description: Social media platform content_type: type: string example: image description: Type of content (e.g., video, image) external_id: type: string example: ABC123xyz description: External platform identifier for the post username: type: string example: tech.trends description: Username of the creator name: type: string example: Tech Trends description: Display name of the creator profile_share_url: type: string example: https://www.instagram.com/tech.trends description: URL to the creator's profile metrics: type: object properties: views: type: integer example: 365558 description: Total views for the post likes: type: integer example: 12460 description: Total likes for the post comments: type: integer example: 37 description: Total comments for the post shares: type: integer example: 5970 description: Total shares for the post description: Engagement metrics for the post gmv: type: string example: $1,284.53 description: >- Gross Merchandise Value for the post (only included when include_gmv=true) '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: required: - error - message type: object properties: error: type: string message: type: string securitySchemes: bearerAuth: type: http scheme: bearer ````