Returns per-post insights for Instagram posts: specific posts by id, or a page
of the newest posts, optionally within a time window. Needs
instagram_manage_insights (Facebook Login and Unified Login) or
instagram_business_manage_insights (Instagram Login); an account with either
reports capabilities["post.analytics"]: true.
Query parameters
accountIduuidRequired- A connected Instagram account.
profileIduuid- Optional, because accountId names its profile. If you pass both, they must agree.
postIdsstring- Comma-separated Instagram media ids (providerId from GET /api/v1/posts), at most 50. Cannot be combined with since, until, or limit.
sinceISO 8601- Only posts published at or after this date or date-time.
untilISO 8601- Only posts published before this date or date-time. Pass nextUntil here for the next, older page.
limitinteger- Posts per page, 1–500. Defaults to 25.
Metrics
Every post has the same metrics object. A metric the post's type does not
report is null without a warning.
| Metric | Feed posts and carousels | Reels | Stories |
|---|---|---|---|
views, reach, shares, totalInteractions | ✓ | ✓ | ✓ |
likes, comments, saves | ✓ | ✓ | |
profileVisits, follows | ✓ | ✓ | |
avgWatchTimeMs, totalWatchTimeMs, skipRate | ✓ | ||
replies, navigation | ✓ | ||
totalViews, totalLikes, totalComments | Facebook Login and Unified Login only | Facebook Login and Unified Login only | totalViews only |
crosspostedViews | Facebook Login and Unified Login, reels shared to Facebook |
- Units. Watch time is in milliseconds, as Instagram reports it.
avgWatchTimeSecandtotalWatchTimeSecgive the same values in seconds, to one decimal place.skipRateis the percentage of views that skipped in the first three seconds. - Organic only. Every metric counts organic activity only, except
totalViews,totalLikesandtotalComments, which include ads and boosted posts and match the Instagram app's dashboard. - Lifetime and delayed. Figures are lifetime totals for the post. Instagram can take up to 48 hours to settle them.
- Stories. Instagram keeps a story's insights for 24 hours after it expires. A story with fewer than 5 viewers reports no figures.
A null metric the post's type should report carries a warnings entry with a
reason: pending (not read yet), not_returned (Instagram had no figure),
unsupported_for_account, not_enough_viewers, unavailable (Instagram
refused the post's insights, as it does for posts made before the account
became a professional account), or rate_limited.
Freshness
Adeli keeps a copy of each post's insights and answers from it, so this
endpoint is fast however many posts an account has. Adeli refreshes the copy in
the background while the account is being read: every 30 minutes for posts
under two days old, then every 6 hours, every day after 30 days, and every week
after 90 days. Each post's fetchedAt says when its figures were read from
Instagram.
sync.status says where the account stands:
fresh: the stored figures are current.refreshing: a background refresh is running. Read again in a minute or two.pending: Adeli has not read this account yet. Its first figures arrive within a few minutes.backoff: Instagram rate-limited the last refresh. It resumes within 15 minutes.
An account with hundreds of posts fills in over a few hours, newest posts and
posts asked for by id first. sync.pendingPosts counts the posts in the
response that are still waiting.
Errors — 401 unauthorized, 400 invalid_request, 403 permission_required,
404 account_not_found, 404 profile_not_found, 422 connection_expired,
422 provider_not_configured, 502 provider_error.