Analytics & 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 allowance.

Analytics covers ten channels: TikTok, Instagram, YouTube, Facebook, LinkedIn, X, Threads, Pinterest, Reddit and Bluesky. Google Business Profile and the manual-credential channels (Telegram, Discord, Slack, Mastodon, Nostr, Lemmy, dev.to, Hashnode, WordPress, Whop, listmonk) can be published to, but report no follower, reach, engagement or impression metrics — leave them out of the platforms list when requesting analytics. See Channels.

Profile analytics

Cross-platform follower, reach, and engagement metrics for a single 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	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).
`location_id`	no	The Google Business location to report on, taken from `google_business_locations` in the response. With one location it is used automatically. With several, the location chosen as default when Google Business was connected is used; if none was chosen, `google_business` returns `code: "location_required"` until you pass one. `google_business_location_id` names the location the numbers are for, and `google_business_location_source` says which rule picked it: `requested`, `only_location` or `connection_default`.

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

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "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.

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

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

The request_id must belong to one of your own posts. Any other id returns 404 not_found.

Publish history

A paginated, newest-first list of everything you’ve published through MADIAD Hub.

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.

{
  "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 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 or check its status.

Per-post metrics over 30 days

Platforms: Instagram · Facebook · YouTube · TikTok · LinkedIn · X · Threads · Pinterest · Reddit · Bluesky. One platform per call.

This answers “how did my recent posts do” — covering posts published through the Hub and posts you published by hand.

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

Optional: since, until, limit. A post published outside the Hub has no request_id to key on. Use the platform’s own id:

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"

Audience — when they are online

Platforms: TikTok only. Others return 400 platform_not_supported naming what is supported. A TikTok account connected before this permission existed must be reconnected.

Not a generic best-time-to-post table: the number of your own followers connected in each hour of the day.

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

Returns country, gender and device breakdowns plus activity_by_hour. Optional start_date, end_date, benchmark_category.

Render the range in the response, not the one you asked for. The platform refuses a window ending today or later and keeps only 60 days, so your request may be trimmed before it runs — the two windows are not always the same.

Hashtag and keyword suggestions

Platforms: TikTok only. type=keywords additionally needs a reconnected TikTok account; type=hashtags works on any recently connected one.

curl "https://api.madiad.com/v1/analytics/suggestions?profile_id=$PROFILE_ID&platform=tiktok&type=hashtags&q=shipping&country_code=VN&language=vi" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

type=hashtags gives the tags to pair with the keyword; type=keywords gives what people search around it.

Only TikTok answers these today; other platforms return 400 with error_code platform_not_supported.A TikTok account connected before this permission existed answers 400 with tiktok_reconnect_required. Reconnect TikTok from Connections and it works — this is not a fault on either side; the permission is granted at the moment the account is connected.

Get Started

Concepts

Integrations

API Reference

Profile analytics

Total impressions

Per-post analytics

Publish history

Per-post metrics over 30 days

Audience — when they are online

Hashtag and keyword suggestions

​Profile analytics

​Total impressions

​Per-post analytics

​Publish history

​Per-post metrics over 30 days

​Audience — when they are online

​Hashtag and keyword suggestions

Profile analytics

Total impressions

Per-post analytics

Publish history

Per-post metrics over 30 days

Audience — when they are online

Hashtag and keyword suggestions