> ## 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 & history

> Pull profile metrics, per-post performance, and your publish history.

MADIAD Hub exposes read-only reporting for the profiles and posts you own. Every endpoint is scoped to your account — profile metrics are keyed by your own `profile_id`, and post metrics require a `request_id` from one of your earlier publishes. These are `GET` requests and do **not** consume your upload or FFmpeg quota.

<Note>
  **Telegram and Discord are not covered by analytics.** You can publish to them, but no follower, reach, engagement, or impression metrics are available — leave them out of the `platforms` list when requesting analytics.
</Note>

## Profile analytics

Cross-platform follower, reach, and engagement metrics for a single 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         | Required | Description                                                                |
| ------------------- | -------- | -------------------------------------------------------------------------- |
| `profile_id`        | yes      | The profile to report on.                                                  |
| `platforms`         | yes      | Comma-separated platforms, e.g. `instagram,tiktok,linkedin`.               |
| `facebook_page_id`  | no       | Report on a specific Facebook Page.                                        |
| `linkedin_page_urn` | no       | Report on a LinkedIn organization page (defaults to the connected member). |

The response wraps the per-platform metric payload under `analytics`:

```json theme={null}
{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "analytics": {
    "instagram": { "followers": 12840, "reach": 90213, "engagement": 0.047 },
    "tiktok":    { "followers": 5320, "views": 412900 }
  }
}
```

## Total impressions

Aggregated impressions for one profile over a date range or a named period.

```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              | Required | Description                                                                |
| ------------------------ | -------- | -------------------------------------------------------------------------- |
| `profile_id`             | yes      | The profile to report on.                                                  |
| `period`                 | no       | One of `last_day`, `last_week`, `last_month`, `last_3months`, `last_year`. |
| `start_date`, `end_date` | no       | `YYYY-MM-DD` range (use instead of `period`).                              |
| `date`                   | no       | A single `YYYY-MM-DD` day.                                                 |
| `platform`               | no       | Restrict to one platform.                                                  |
| `breakdown`              | no       | `true` to include a per-platform / per-day breakdown.                      |
| `metrics`                | no       | Comma-separated metrics, e.g. `reach,views,likes,comments`.                |

## Per-post analytics

Performance for a single post, identified by the `request_id` returned when you published it.

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

<Note>
  The `request_id` must belong to one of your own posts. Any other id returns `404 not_found`.
</Note>

## Publish history

A paginated, newest-first list of everything you've published through 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  | Required | Description                               |
| ------------ | -------- | ----------------------------------------- |
| `page`       | no       | 1-based page number (default `1`).        |
| `limit`      | no       | Items per page, `1`–`100` (default `20`). |
| `profile_id` | no       | Filter to a single 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` uses the same vocabulary as a publish response — `completed`, `partial`, `failed` or `unknown` — and `error` carries the reason when it is not `completed`. A post published asynchronously is recorded as accepted and settled to its real outcome once the platform answers, so a recent item can move from `completed` to `partial` or `failed` within the day.

Use the `request_id` from a history item to fetch its [per-post analytics](#per-post-analytics) or [check its status](/concepts/posts).