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: Instagram đang hạn chế tài khoản này…"
    }
  ]
}

status dùng đúng bộ từ vựng của response lệnh đăng: completed, partial, failed hoặc unknown. Trường error nêu lý do khi trạng thái không phải completed. 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, nên 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, gồm cả bài đăng qua Hub lẫn bài bạn đăng tay.

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. Một bài đăng ngoài Hub thì không có request_id để tra. 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á