Analytics & lịch sử

MADIAD Hub cung cấp báo cáo chỉ đọc cho các Profile và bài đăng của bạn. Mọi endpoint đều giới hạn trong phạm vi tài khoản, số liệu Profile được khóa theo profile_id của chính bạn, còn số liệu bài đăng yêu cầu request_id từ một lần đăng trước đó. Đây là các request GET và không tiêu tốn quota upload hay FFmpeg.

Analytics có số liệu cho mười kênh: TikTok, Instagram, YouTube, Facebook, LinkedIn, X, Threads, Pinterest, Reddit và Bluesky. Google Business Profile và các kênh nhập thủ công (Telegram, Discord, Slack, Mastodon, Nostr, Lemmy, dev.to, Hashnode, WordPress, Whop, listmonk) vẫn đăng bài được, nhưng không có số liệu người theo dõi, phạm vi tiếp cận, tương tác hay lượt hiển thị. Hãy bỏ chúng khỏi danh sách platforms khi gọi analytics. Xem Kênh.

Analytics theo Profile

Số liệu follower, reach và engagement đa nền tảng cho một Profile.

curl "https://api.madiad.com/v1/analytics/profile?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83&platforms=instagram,tiktok,youtube" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Query param	Bắt buộc	Mô tả
`profile_id`	có	Profile cần báo cáo.
`platforms`	có	Danh sách nền tảng phân tách bằng dấu phẩy, ví dụ `instagram,tiktok,linkedin`.
`facebook_page_id`	không	Báo cáo cho một Facebook Page cụ thể.
`linkedin_page_urn`	không	Báo cáo cho một trang tổ chức LinkedIn (mặc định là tài khoản đã kết nối).
`location_id`	không	Địa điểm Google Business cần báo cáo, lấy từ `google_business_locations` trong response. Profile chỉ có một địa điểm thì tự dùng địa điểm đó. Có nhiều địa điểm thì dùng địa điểm mặc định đã chọn lúc kết nối Google Business; nếu chưa chọn, `google_business` trả `code: "location_required"` cho tới khi bạn truyền một địa điểm. `google_business_location_id` là địa điểm của số liệu, còn `google_business_location_source` cho biết đã chọn theo cách nào: `requested`, `only_location` hoặc `connection_default`.

Response gói payload số liệu theo nền tảng dưới khóa analytics:

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "analytics": {
    "instagram": { "followers": 12840, "reach": 90213, "engagement": 0.047 },
    "tiktok":    { "followers": 5320, "views": 412900 }
  }
}

Tổng impressions

Tổng hợp impressions cho một Profile theo khoảng ngày hoặc theo một mốc thời gian định sẵn.

curl "https://api.madiad.com/v1/analytics/impressions?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83&period=last_month&breakdown=true" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Query param	Bắt buộc	Mô tả
`profile_id`	có	Profile cần báo cáo.
`period`	không	Một trong `last_day`, `last_week`, `last_month`, `last_3months`, `last_year`.
`start_date`, `end_date`	không	Khoảng `YYYY-MM-DD` (dùng thay cho `period`).
`date`	không	Một ngày `YYYY-MM-DD` duy nhất.
`platform`	không	Giới hạn về một nền tảng.
`breakdown`	không	`true` để kèm chi tiết theo nền tảng hoặc theo ngày.
`metrics`	không	Danh sách metrics phân tách bằng dấu phẩy, ví dụ `reach,views,likes,comments`.

Analytics theo từng bài

Hiệu suất của một bài đăng, xác định bằng request_id trả về khi bạn đăng bài đó.

curl "https://api.madiad.com/v1/analytics/post?request_id=req_01HZX9H6S8T0V2W4X6Y8Z0A2B4" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

request_id phải thuộc về một bài đăng của chính bạn. Mọi id khác sẽ trả về 404 not_found.

Lịch sử đăng bài

Danh sách phân trang, mới nhất trước, của mọi thứ bạn đã đăng qua MADIAD Hub.

curl "https://api.madiad.com/v1/posts/history?page=1&limit=20" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Query param	Bắt buộc	Mô tả
`page`	không	Số trang tính từ 1 (mặc định `1`).
`limit`	không	Số mục mỗi trang, từ `1` đến `100` (mặc định `20`).
`profile_id`	không	Lọc theo một Profile.

{
  "page": 1,
  "limit": 20,
  "total": 134,
  "items": [
    {
      "id": "evt_01HZX9J8T0V2W4X6Y8Z0A2B4C6",
      "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
      "type": "video",
      "platforms": ["tiktok", "instagram"],
      "request_id": "req_01HZX9H6S8T0V2W4X6Y8Z0A2B4",
      "created_at": "2026-06-15T08:30:00Z",
      "status": "partial",
      "error": "Instagram: Action suspected as spam. Activity is restricted. · Tạm dịch: Hoạt động bị nghi là spam. Tài khoản đang bị hạn chế thao tác."
    }
  ]
}

status dùng đúng bộ từ vựng của response lệnh đăng: completed, draft, partial, failed hoặc unknown, thêm canceled cho bài hẹn giờ đã hủy trước khi chạy, và error nêu lý do khi bài bị từ chối. Khi có nền tảng từ chối bài, trường này nêu tên từng nền tảng đó, kèm câu của chính nền tảng và, khi Hub có bản dịch tiếng Việt, phần dịch nằm sau · Tạm dịch:. Bài đăng bất đồng bộ được ghi nhận là đã tiếp nhận, rồi được chốt lại theo kết quả thật khi nền tảng trả lời: thường là lúc nền tảng báo đã xử lý xong bài, còn không thì ở lần kiểm tra hằng ngày. Vì vậy một mục vừa đăng có thể chuyển từ completed sang partial hoặc failed trong ngày. Dùng request_id từ một mục lịch sử để lấy analytics theo từng bài hoặc kiểm tra trạng thái của nó.

Số liệu từng bài trong 30 ngày

Kênh áp dụng: Instagram · Facebook · YouTube · TikTok · LinkedIn · X · Threads · Pinterest · Reddit · Bluesky. Truyền một platform mỗi lần gọi.

Câu hỏi “mấy bài gần đây chạy thế nào” trả lời ở đây: danh sách các bài Profile đã đăng trên một kênh, mới nhất trước, kèm số liệu đã biết của từng bài.

curl "https://api.madiad.com/v1/analytics/posts?profile_id=$PROFILE_ID&platform=facebook" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Tuỳ chọn: since, until, limit, seed. Bài đăng qua Hub có trong danh sách khi kênh đã trả về mã bài (100 bài mới nhất của mỗi kênh trong khoảng thời gian). Số liệu của một bài chỉ có sau khi được đọc từ kênh: bài chưa được đọc thì metrics và captured_at là null (không phải 0). Mỗi lần gọi, Hub đọc tối đa 6 bài như vậy trong chính danh sách trả về, bài mới nhất trước, nên một kênh có nhiều bài sẽ có thêm số sau mỗi lần gọi. Bài mà kênh không cho số liệu (bài đã bị gỡ, hoặc loại bài kênh không thống kê) thì vẫn là null, và Hub để yên bài đó khoảng 30 phút trước khi thử lại. captured_at cho biết số liệu của bài được đọc lúc nào. Chỉ cần danh sách bài thì truyền seed=false, Hub không đọc số liệu bài nào trong lần gọi đó. limit mặc định 50, tối đa 200. limit và has_more trong kết quả nói về chính danh sách trả về (không có con trỏ trang: muốn xem thêm thì tăng limit); cached_posts_in_range và published_posts_in_range là bộ đếm của kho số liệu. Trên trang Phân tích, mục “Từng bài · 30 ngày” dùng chính lệnh này: chọn kênh là danh sách tải ngay. Một bài đăng ngoài Hub thì không có request_id để tra, và chỉ có trong danh sách trên sau khi số liệu của nó được đọc một lần. Dùng id của nền tảng:

curl "https://api.madiad.com/v1/analytics/post-organic?profile_id=$PROFILE_ID&platform=facebook&platform_post_id=$POST_ID" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Khán giả: họ online giờ nào

Kênh áp dụng: chỉ TikTok. Kênh khác trả 400 platform_not_supported kèm danh sách đang hỗ trợ. Tài khoản TikTok nối trước khi quyền này ra đời phải nối lại.

Không phải bảng “giờ vàng đăng bài” chung chung, mà là số người theo dõi của chính tài khoản bạn có mặt trong từng giờ trong ngày.

curl "https://api.madiad.com/v1/analytics/audience?profile_id=$PROFILE_ID&platform=tiktok" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Trả về phân bố quốc gia, giới tính, thiết bị và activity_by_hour. Tuỳ chọn start_date, end_date, benchmark_category.

Hãy hiển thị range trong phản hồi, không phải khoảng bạn đã hỏi. Nền tảng từ chối khoảng kết thúc từ hôm nay trở đi và chỉ giữ 60 ngày, nên yêu cầu của bạn có thể bị cắt bớt trước khi chạy. Hai khoảng không phải lúc nào cũng trùng nhau.

Gợi ý hashtag và từ khoá

Kênh áp dụng: chỉ TikTok. Riêng type=keywords cần tài khoản TikTok đã nối lại; type=hashtags chạy trên tài khoản nối gần đây là đủ.

curl "https://api.madiad.com/v1/analytics/suggestions?profile_id=$PROFILE_ID&platform=tiktok&type=hashtags&q=g%E1%BB%ADi%20h%C3%A0ng&country_code=VN&language=vi" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

type=hashtags là các thẻ nên đi kèm từ khoá; type=keywords là những gì người ta tìm quanh nó.

Hai nhóm trên hiện chỉ TikTok trả lời; nền tảng khác trả 400 với error_code platform_not_supported.Nếu tài khoản TikTok được kết nối từ trước khi quyền này ra đời, bạn sẽ nhận 400 với tiktok_reconnect_required. Vào Kết nối và nối lại TikTok là xong. Đây không phải lỗi ở hai phía, mà là quyền phải được cấp đúng lúc kết nối.

Bắt đầu

Khái niệm

Tích hợp

Tham chiếu API

Analytics & lịch sử

Analytics theo Profile

Tổng impressions

Analytics theo từng bài

Lịch sử đăng bài

Số liệu từng bài trong 30 ngày

Khán giả: họ online giờ nào

Gợi ý hashtag và từ khoá

​Analytics theo Profile

​Tổng impressions

​Analytics theo từng bài

​Lịch sử đăng bài

​Số liệu từng bài trong 30 ngày

​Khán giả: họ online giờ nào

​Gợi ý hashtag và từ khoá

Analytics theo Profile

Tổng impressions

Analytics theo từng bài

Lịch sử đăng bài

Số liệu từng bài trong 30 ngày

Khán giả: họ online giờ nào

Gợi ý hashtag và từ khoá