Get post data of a TikTok account
GET/business/video/list/Gọi qua 360: GET https://partner.quantri360.com/v1/tiktok_business/business/video/list/
Mô tả API
Danh sách bài đăng công khai (video, ảnh, văn bản) của tài khoản TikTok Business kèm số liệu tiếp cận và tương tác: lượt xem, thích, bình luận, chia sẻ, tiếp cận, thời gian xem, nguồn lượt xem, khán giả theo giới tính / quốc gia / thành phố. Gồm cả video "Chỉ hiển thị trong quảng cáo" (không nằm trên trang cá nhân nhưng xem công khai được qua quảng cáo).
- Số tương tác tính trọn đời video (không giới hạn 60 ngày như số liệu cấp tài khoản); bài đăng quá 365 ngày ngừng cập nhật số liệu.
- Số liệu chỉ có khi TikTok Analytics của tài khoản có (chủ tài khoản phải đăng ít nhất 1 video và bật Analytics trong app).
reach,full_video_watched_rate,total_time_watched,average_time_watched,impression_sources,audience_countriestrống thường do video không có tương tác quá 7 ngày — chờ 24–48 giờ sau khi video có lượt xem / tương tác lại.- Bài vi phạm (vd bản quyền nhạc) bị TikTok lọc khỏi kết quả.
- Thiếu quyền của một trường → TikTok báo lỗi; bỏ trường đó khỏi
fieldshoặc ủy quyền lại tài khoản với quyền tương ứng.
Request
Địa chỉ
GET https://partner.quantri360.com/v1/tiktok_business/business/video/list/
Xác thực & gian hàng
| Tên | Vị trí | Kiểu | Mẫu | Mô tả |
|---|---|---|---|---|
| Authorization | header | header | Bearer q360_live_ab12cd34_… | Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand. |
| platform_shop_id | query | string | 7000000000000000001 | Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản. |
Tham số request
| Tên | Vị trí | Kiểu | Bắt buộc | Mẫu | Mô tả |
|---|---|---|---|---|---|
| fields | query | string[] | Không | ["item_id","create_time","caption","share_url","likes","comments","shares","video_views","reach"] | Mảng JSON các trường cần lấy, PHẢI có "item_id". Không gửi = chỉ trả item_id. Mỗi trường cần một quyền (scope) của tài khoản: video.list — item_id, media_type, is_ad, thumbnail_url, share_url, embed_url, caption, video_duration, likes, comments, shares, favorites, create_time, reach, video_views; video.insights — total_time_watched, average_time_watched, full_video_watched_rate, new_followers, profile_views, website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks, address_clicks, video_view_retention, impression_sources, audience_genders, audience_countries, audience_cities, audience_types, engagement_likes. |
| filters | query | object | Không | {"video_ids":["7563000000000000001"]} | Lọc theo bài, gửi dạng chuỗi JSON: video_ids (mảng id bài) và ad_post_only (true = chỉ bài đã cấp quyền tạo Spark Ads; chỉ có tác dụng khi có video_ids, mặc định false). |
| cursor | query | int | Không | Con trỏ trang = mốc thời gian Unix mili giây (UTC). Mặc định = hiện tại. Trang kế: truyền data.cursor của trang trước. Tự đặt mốc để lấy các bài đăng TRƯỚC thời điểm đó. | |
| max_count | query | int | Không | 20 | Số bài mỗi trang. Mặc định 10, tối đa 20. TikTok có thể trả ít hơn dù has_more = true (bài bị lọc theo chính sách an toàn). |
Phân trang
Lặp khi data.has_more = true, truyền cursor = data.cursor cho lần gọi kế; dừng khi has_more = false.
Ví dụ request
curl -s "https://partner.quantri360.com/v1/tiktok_business/business/video/list/?platform_shop_id=-000AbCdEfGhIjKlMnOpQrStUvWxYz012345&fields=%5B%22item_id%22%2C%22create_time%22%2C%22caption%22%2C%22share_url%22%2C%22likes%22%2C%22comments%22%2C%22shares%22%2C%22video_views%22%2C%22reach%22%5D&max_count=20" \ -H "Authorization: Bearer $KEY"
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.get(
"https://partner.quantri360.com/v1/tiktok_business/business/video/list/",
params={
"platform_shop_id": "-000AbCdEfGhIjKlMnOpQrStUvWxYz012345",
"fields": [
"item_id",
"create_time",
"caption",
"share_url",
"likes",
"comments",
"shares",
"video_views",
"reach"
],
"max_count": 20
},
headers={"Authorization": f"Bearer {KEY}"},
timeout=60,
)
print(r.status_code)
print(r.json())Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/business/video/list/');
for (const [k, v] of Object.entries({"platform_shop_id":"-000AbCdEfGhIjKlMnOpQrStUvWxYz012345","fields":["item_id","create_time","caption","share_url","likes","comments","shares","video_views","reach"],"max_count":20})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'GET',
headers: { Authorization: `Bearer ${KEY}` },
});
console.log(r.status, await r.json());PHP
<?php $key = 'q360_live_...'; // khóa API của brand $url = 'https://partner.quantri360.com/v1/tiktok_business/business/video/list/' . '?' . http_build_query(['platform_shop_id' => '-000AbCdEfGhIjKlMnOpQrStUvWxYz012345', 'fields' => '["item_id","create_time","caption","share_url","likes","comments","shares","video_views","reach"]', 'max_count' => 20]); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]); $res = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo $status, "\n", $res;
Response
Tham số phản hồi (nguyên của TikTok Business)
| Tên | Kiểu | Mẫu | Mô tả |
|---|---|---|---|
| code | int | 0 | 0 = thành công; khác 0 xem `message` (TikTok trả HTTP 200 kèm code lỗi). |
| message | string | OK | Thông điệp của TikTok. |
| request_id | string | 2021080307532501024502410704A7306F | Mã request TikTok — ghi lại khi cần tra lỗi. |
| data | object | Dữ liệu. | |
| videos | object[] | Bài đăng (chỉ có các trường đã yêu cầu ở `fields`). | |
| item_id | string | 6995316737801538821 | Id bài. Quyền: video.list. |
| media_type | string | VIDEO | `VIDEO` = video · `PHOTO` = ảnh hoặc văn bản. Quyền: video.list. |
| is_ad | bool | false | Bài đang được dùng trong quảng cáo (Spark Ads). Quyền: video.list. |
| create_time | string | 1628461703 | Thời điểm đăng, Unix giây (UTC). Quyền: video.list. |
| caption | string | Mô tả bài. Quyền: video.list. | |
| thumbnail_url | string | Ảnh thu nhỏ — link TẠM, hết hạn theo tham số `x-expires` (Unix giây). Quyền: video.list. | |
| share_url | string | https://www.tiktok.com/@…/video/6994189750940863749 | Link chia sẻ. Quyền: video.list. |
| embed_url | string | https://www.tiktok.com/player/v1/… | Link nhúng; bài để chế độ "Bạn bè" / "Chỉ mình tôi" không xem được qua link này. Quyền: video.list. |
| video_duration | float | 20.001 | Độ dài video (giây). Trễ 24–48 giờ. Quyền: video.list. |
| likes | int | 243 | Lượt thích. Trễ 24–48 giờ. Quyền: video.list. |
| comments | int | 10 | Lượt bình luận. Trễ 24–48 giờ. Quyền: video.list. |
| shares | int | 10 | Lượt chia sẻ (gồm chia sẻ ra ngoài và "Gửi cho bạn bè" trong app). Trễ 24–48 giờ. Quyền: video.list. |
| favorites | int | 10 | Lượt thêm vào yêu thích. Trễ 24–48 giờ. Quyền: video.list. |
| video_views | int | 603 | Lượt xem — gồm cả tự nhiên lẫn trả phí. Trễ 24–48 giờ. Quyền: video.list. |
| reach | int | 136 | Số người đã xem ít nhất một lần. Trễ 24–48 giờ. Quyền: video.list. |
| total_time_watched | float | 587.024 | Tổng thời gian xem (giây). Quyền: video.insights. |
| average_time_watched | float | 3.862 | Thời gian xem trung bình (giây). Quyền: video.insights. |
| full_video_watched_rate | float | 0.0395 | Tỉ lệ xem hết video (0–1). Quyền: video.insights. |
| new_followers | int | Người theo dõi mới từ bài. Quyền: video.insights. | |
| profile_views | int | Lượt xem trang cá nhân từ bài — chỉ tài khoản Advanced Access hoặc doanh nghiệp đã xác minh. Quyền: video.insights. | |
| website_clicks | int | Nhấn link website từ bài. Chỉ tài khoản doanh nghiệp đã xác minh (cùng điều kiện cho phone_number_clicks, lead_submissions, app_download_clicks, email_clicks, address_clicks). Quyền: video.insights. | |
| impression_sources | object[] | Nguồn lượt xem. Quyền: video.insights. | |
| impression_source | string | For You | For You · Follow · Personal Profile · Hashtag · Sound · Search… |
| percentage | float | 0.8983 | Tỉ lệ (0–1). |
| audience_countries | object[] | Khán giả theo quốc gia (top). Quyền: video.insights. | |
| country | string | VN | |
| percentage | float | ||
| audience_cities | object[] | Khán giả theo thành phố (top). Quyền: video.insights. | |
| city_name | string | ||
| percentage | float | ||
| audience_genders | object[] | Khán giả theo giới tính. Quyền: video.insights. | |
| gender | string | Female | |
| percentage | float | ||
| audience_types | object[] | Người xem mới / quay lại, theo dõi / chưa theo dõi. Quyền: video.insights. | |
| type | string | ||
| percentage | float | ||
| video_view_retention | object[] | Tỉ lệ người còn xem theo giây. Quyền: video.insights. | |
| second | string | ||
| percentage | float | ||
| engagement_likes | object[] | Phân bố lượt thích theo giây của video. Quyền: video.insights. | |
| second | string | ||
| percentage | float | ||
| cursor | int | 1760893200000 | Con trỏ cho trang kế (Unix mili giây). |
| has_more | bool | true | Còn trang kế. |
Bắt đầu dùng
- Đăng ký tài khoản Partner
- Mở loại dữ liệu thuộc nhóm Tài khoản TikTok (Organic API) ở trang nền tảng
- Tạo API key (tick kênh TikTok Business)
- Gọi theo ví dụ ở trên