Instagram Reels reference
Instagram insights API: read your Reels metrics correctly
The Instagram insights API lets an authorized app read media and account metrics for professional Instagram accounts. If you post your Reels with Postdom, you can skip that setup: Postdom stores a performance snapshot for each post and shows which fields are covered.
Updated
Which Instagram insights API path do you need?
Pick the path by the data you need: one Reel, a whole account, or a post you published through Postdom.
The Instagram insights API is the part of Meta's Instagram Platform that returns metrics for a professional account and its media, such as reach, likes, comments, shares and saves.
- One Reel, through Meta: call the media object's
/insightsendpoint with its Instagram media ID. A public Reel URL is not that ID. - An account report, through Meta: call the professional account's
/insightsendpoint and pick metrics from the account reference. - A Postdom post: call
/v1/posts/:id/performancewith your Postdom post ID. It reads stored, normalized snapshots, not a live Meta query.
Meta's paths need a professional account (business or creator), an authorized Meta app and the right permissions for your login path. A Postdom API key is not a Meta access token.
| Login path | Host and token | Insights permissions |
|---|---|---|
| Instagram Login | graph.instagram.comInstagram User access token | instagram_business_basicinstagram_business_manage_insights |
| Facebook Login | graph.facebook.comFacebook User access token | instagram_basicinstagram_manage_insightspages_read_engagement |
A media request for shares and comments looks like this. It is a template from Meta's documentation, not a request Postdom ran.
curl --get \
"https://graph.instagram.com/$META_API_VERSION/$IG_MEDIA_ID/insights" \
--header "Authorization: Bearer $INSTAGRAM_USER_ACCESS_TOKEN" \
--data-urlencode "metric=shares,comments"Instagram graph API
The Instagram graph API is the name many developers still use for Meta's Instagram Platform: the API that publishes media, reads insights and manages comments for professional accounts. Insights are one part of it, served by the /insights endpoints on a media object or an account.
You reach it through an authorized Meta app with Instagram Login or Facebook Login, and each login path needs its own permissions. Personal accounts are not covered. For publishing, login paths and access, read the Instagram API explainer.
Instagram Reels insights: what Postdom returns
Postdom models 9 normalized fields for a Reel. Each one has a coverage state from Postdom's integration record. A state says what Postdom supports, not that every snapshot holds a number.
| Postdom field | Coverage | How to read it | Field verification |
|---|---|---|---|
Viewsviews | Availableavailable | The normalized view count for a Reel performance snapshot. Supported by Postdom. Availability does not guarantee a value in every observation. | |
Likeslikes | Availableavailable | The normalized like count for a Reel performance snapshot. Supported by Postdom. Availability does not guarantee a value in every observation. | |
Commentscomments | Availableavailable | The normalized comment count for a Reel performance snapshot. Supported by Postdom. Availability does not guarantee a value in every observation. | |
Sharesshares | Availableavailable | The normalized share count for a Reel performance snapshot. Supported by Postdom. Availability does not guarantee a value in every observation. | |
Savessaves | Unverifiedunverified | For this state, the normalizer keeps saves null even if an input supplies a number. Postdom has not verified this field's availability. | Not verified |
Watch timewatch_time_s | Availableavailable | Nullable total watch time in seconds. Reels watch-time inputs in milliseconds are converted to seconds. Supported by Postdom. Availability does not guarantee a value in every observation. | |
Average watch percentageavg_watch_pct | Estimableestimable | Nullable percentage. The normalizer prefers a supplied percentage. Otherwise, it can estimate it from average watch time and a positive video duration. An estimate needs suitable inputs; this label does not mean one was computed. | |
Completion percentagecompletion_pct | Estimableestimable | Nullable percentage. The normalizer accepts a supplied completion value; it does not derive completion from average watch time. Without that input, the field stays null. An estimate needs suitable inputs; this label does not mean one was computed. | |
Follower deltafollower_delta | Estimableestimable | A nullable account-level change, not followers attributed to this Reel. The post normalizer leaves this field null. An estimate needs suitable inputs; this label does not mean one was computed. |
Newest dated field check: . This date does not verify saves. Each field has its own timestamp in the table. These are Postdom's recorded integration checks, not a fresh test of every native Meta metric.
Instagram API metrics: watch time and percentages
Total watch time and average watch time answer different questions. Postdom turns watch-time inputs in milliseconds into seconds, and can estimate an average watched percentage from the average watch time and the video's length.
Try the calculation below. It runs Postdom's own normalizer in your browser, with no API call.
Local example only. No API call, account access, or video inspection. Blank means missing input, not zero. The example counts are illustrative.
- watch_time_s
- 720 seconds
- avg_watch_pct
- 50%
A supplied average percentage takes precedence. Without it, the calculation needs average watch time and a duration greater than zero. Postdom caps its normalized percentage at 100%.
Completion and follower delta remain null in this example. An average does not tell you how many viewers finished or followed.
Free Instagram insights API option: read snapshots with Postdom
Postdom posts to Instagram on every plan, and Starter, Growth and Scale start with a 7-day free trial. The Postdom API comes with every plan, so you can read the stored snapshot of a post you published with Postdom at no extra cost.
Call get_performance with your Postdom post ID, or use the HTTP endpoint below. Read the row for platform: "instagram" and keep its capture time beside the values.
curl "https://api.postdom.com/v1/posts/$POSTDOM_POST_ID/performance" \
--header "Authorization: Bearer $POSTDOM_API_KEY"Zero is a value; null is missing. Show a recorded zero as zero. Leave a null field out of totals and averages instead of counting it as zero.
An empty result needs context. An empty performance array means no stored snapshot yet. Check eligibility before you retry.
Related: YouTube analytics API, TikTok analytics API and social media analytics.
Instagram insights API questions
Can I use the Instagram insights API for a personal account?
No. Meta's media insights are for professional Instagram accounts (business or creator). Personal-account media is not covered.
Is a Postdom snapshot the same as a Meta insights response?
No. Postdom returns normalized fields with a coverage state for each. Meta's native response lists metric entries under data. Do not mix the two.
Why is a field null in a Postdom snapshot?
Because Postdom has no backed value for it. Its coverage state in the table says why. Keep it missing in comparisons rather than treating it as zero.
Does reading performance refresh Instagram right away?
No. The Postdom endpoint reads stored snapshots. Check captured_at to see when a value was recorded.
Is Instagram's API free?
Meta doesn't charge for Instagram Platform API calls. You need a Meta app, a professional account and the right permissions, and calls are rate limited.
Is there a public API available for Instagram?
Yes, for professional accounts (business or creator) through Meta's Instagram Platform. Personal accounts are not covered: Meta retired its Basic Display API in December 2024.
What is the 5-3-1 rule on Instagram?
It's an informal growth habit, not an Instagram rule: each day, like 5 posts, comment on 3 and follow 1 account in your niche. Instagram doesn't publish it. Treat it as a routine to test against your own reach, not a guarantee. The insights API can show whether your reach changed.
Post your Reels with Postdom, then read the results
Postdom turns your website into ready-to-post videos, slideshows and single images in your brand, and posts the ones you approve to TikTok, Instagram and more. After a Reel goes out, its snapshot is one call away.
Nothing posts until you approve it. Start with a 7-day free trial.
Start your free trial
Paste your website and see your first post today.