> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madiad.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics & lịch sử

> Lấy số liệu Profile, hiệu suất từng bài, và lịch sử đăng bài của bạn.

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.

<Note>
  **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.
</Note>

## Analytics theo Profile

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

```bash theme={null}
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`:

```json theme={null}
{
  "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.

```bash theme={null}
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 đó.

```bash theme={null}
curl "https://api.madiad.com/v1/analytics/post?request_id=req_01HZX9H6S8T0V2W4X6Y8Z0A2B4" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

<Note>
  `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`.
</Note>

## 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.

```bash theme={null}
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.                               |

```json theme={null}
{
  "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](#analytics-theo-từng-bài) hoặc [kiểm tra trạng thái](/vi/concepts/posts) của nó.