Get Top Posts By Views

cURL

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

import requests

url = "https://api.growi.io/api/public/v1/stats/top_posts_by_views"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.growi.io/api/public/v1/stats/top_posts_by_views', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.growi.io/api/public/v1/stats/top_posts_by_views",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.growi.io/api/public/v1/stats/top_posts_by_views"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.growi.io/api/public/v1/stats/top_posts_by_views")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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"
      }
    ]
  }
}

{
  "error": "<string>",
  "message": "<string>"
}

GET

stats

top_posts_by_views

cURL

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

import requests

url = "https://api.growi.io/api/public/v1/stats/top_posts_by_views"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.growi.io/api/public/v1/stats/top_posts_by_views', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.growi.io/api/public/v1/stats/top_posts_by_views",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.growi.io/api/public/v1/stats/top_posts_by_views"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.growi.io/api/public/v1/stats/top_posts_by_views")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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"
      }
    ]
  }
}

{
  "error": "<string>",
  "message": "<string>"
}

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

Top posts by views retrieved successfully

success

boolean

Example:

true

data

object

Show child attributes

Get Started

Essentials

API Documentation

Tracking Events

Stats API

TikTok Shop API

Organization API

Conversions API

Request Parameters

Example

Response Fields

Request Example

Response Example

Authorizations

Query Parameters

Response

​Request Parameters

​Example

​Response Fields

​Request Example

​Response Example

Authorizations

Query Parameters

Response

Request Parameters

Example

Response Fields

Request Example

Response Example