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.

Telegram và Discord không có analytics. Bạn vẫn đăng bài được lên hai nền tảng này, 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.

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=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z&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).

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

{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "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=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z&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": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
      "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ó.

Bắt đầu

Khái niệm

Tích hợp

Analytics & lịch sử

Analytics theo Profile

Tổng impressions

Analytics theo từng bài

Lịch sử đăng bài

​Analytics theo Profile

​Tổng impressions

​Analytics theo từng bài

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

Analytics theo Profile

Tổng impressions

Analytics theo từng bài

Lịch sử đăng bài