One Reel, through Meta
Use a media object's /insights endpoint with its Instagram media ID. An account ID or public Reel URL is not that media ID.
Instagram Reels · developer guide
Instagram insights API: read your Reels metrics correctly
The Instagram insights API lets authorized apps read media and account metrics for professional Instagram accounts. Use Meta's native Insights endpoints for those reports, or Postdom's performance endpoint for a Reel published through Postdom. They return different shapes: native metrics are not interchangeable with Postdom's normalized fields.
Which Instagram insights API path do you need?
An account report, through Meta
Use the professional account's /insights endpoint. Select metrics and periods from the account reference, not the media list.
A Postdom post snapshot
Use your Postdom post ID with /v1/posts/:id/performance. This reads stored normalized observations, not an arbitrary Meta Insights query.
Match the login, host, and token
You need a professional account (business or creator), an authorized Meta app, and permissions for the chosen 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 |
Facebook Login requires a linked Facebook Page. Additional Business Manager permissions can apply. Standard Access covers accounts you own or manage and add to your app; other customers' accounts require Advanced Access. Follow Meta's Insights setup guide for the full conditions.
Start with a media request
This shell template is adapted from Meta's Media Insights reference to request shares and comments. Set the API version supported by your app, the authorized account's media ID, and its Instagram User access token. It uses Instagram Login; do not mix in the Facebook host or token.
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"Documentation-based template, not a live request run by Postdom. The native response contains metric entries under data, with names, periods, and values. It is not the Postdom snapshot below. Confirm metric eligibility for the media type and API version before expanding the request.
Which Reels metrics can Postdom return?
Postdom's 9 normalized fields currently cover 5 available, 3 estimable, and 1 unverified. Availability describes integration coverage, not a promise that every response contains a number. These field names are not a list of native Meta query parameters.
| 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.
Coverage sources and field-specific evidence
Postdom's destination metric reference explains the normalized states. The internal evidence reference identifies the check behind each row; it does not replace Meta's native endpoint documentation.
views:docs/verification/metric-availability.mdlikes:docs/verification/metric-availability.mdcomments:docs/verification/metric-availability.mdshares:docs/verification/metric-availability.mdsaves:docs/verification/metric-availability.md. Recorded reason: instagram.saves is unverified; no evidence-backed value is available yet.watch_time_s:docs/verification/metric-availability.mdavg_watch_pct:docs/verification/metric-availability.mdcompletion_pct:docs/verification/metric-availability.mdfollower_delta:docs/verification/metric-availability.md
How do milliseconds become watch seconds and a percentage?
Postdom accepts several watch-time inputs in its provider payload. The names in this example are normalizer inputs, not a native Meta request or response. Total watch time and average watch time answer different questions: one adds viewing time; the other describes an average view.
total milliseconds ÷ 1,000 → watch_time_s(average milliseconds ÷ 1,000) ÷ duration seconds × 100 → avg_watch_pctWith the default illustrative inputs, total watch time becomes 720 seconds and average watch becomes 50%. A supplied average percentage wins over that calculation. A missing or zero duration cannot support the estimate.
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.
Average watch is not completion
Completion percentage: Estimable. An estimate needs suitable inputs; this label does not mean one was computed. 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. Read what completion rate means and how to handle a missing value.
Follower change is not Reel attribution
Follower delta: Estimable. An estimate needs suitable inputs; this label does not mean one was computed. A nullable account-level change, not followers attributed to this Reel. The post normalizer leaves this field null.
How do you read a Postdom performance snapshot?
For a post in your Postdom organization, call get_performance with { "post_id": "YOUR_POSTDOM_POST_ID" }, or use the HTTP endpoint below. With the MCP tool, supply either post_id or account_id, not both.
curl "https://api.postdom.com/v1/posts/$POSTDOM_POST_ID/performance" \
--header "Authorization: Bearer $POSTDOM_API_KEY"The response has post_id, a performance array, eligibility, and a summary. Rows include publish_id and per-field availability. Read the row for platform: "instagram" and keep its capture time alongside the values.
Illustrative normalized snapshot from the default inputs
This is the normalized portion of a row, not a complete API response or a real Reel. Counts and capture time are invented example inputs. Its values are produced by Postdom's actual normalizer using the calculator's defaults, not your edits.
{
"views": 120,
"likes": 8,
"comments": 0,
"shares": 2,
"saves": null,
"watch_time_s": 720,
"avg_watch_pct": 50,
"completion_pct": null,
"follower_delta": null,
"captured_at": "2026-01-01T12:00:00.000Z",
"platform": "instagram",
"source": "poll"
}A number can be zero
The illustrative snapshot supplies comments: 0. Display it as zero. Do not use zero to fill a missing input: without required views, likes, comments, or shares, Postdom's normalizer returns no snapshot.
Null needs its coverage state
Saves: Unverified. Postdom has not verified this field's availability. For this state, the normalizer keeps saves null even if an input supplies a number. This is a Postdom evidence gap, not a statement that Meta cannot report saves.
An empty array needs context
An empty performance array means no stored observations. Read eligibility: ineligible with publish_failed means the publish failed before producing a measurable post. eligible is not a promise of future data.
When should you check again?
There is no verified Instagram reporting-delay window, rate-limit number, or quota cost in Postdom's coverage records. Do not promise an update by a fixed deadline. Check the snapshot's captured_at before comparing it with an earlier observation; repeated reads are not a request to refresh Meta's data.
Meta's account Insights guide separately warns that unavailable data may be an empty dataset instead of a zero-valued metric. Do not treat that native response shape as Postdom's null convention. Read Meta's account Insights limitations.
Common implementation questions
Can I use Insights for a personal account?
Meta's media Insights access is for professional Instagram accounts, not personal-account media. Use the setup guide for the login path your app implements.
Why is saves null in a Postdom snapshot?
Saves: Unverified. Postdom has not verified this field's availability. For this state, the normalizer keeps saves null even if an input supplies a number. Keep it missing in comparisons, rather than treating it as zero saves.
Does estimable mean a percentage is always returned?
No. An estimate needs suitable inputs. Average watch percentage can use average watch time and a positive video duration; completion is not derived from that average. The post normalizer leaves follower_delta null.
Does reading performance refresh Instagram immediately?
No. The Postdom performance endpoint reads stored snapshots. Check captured_at to see when an observation was recorded; a successful read does not guarantee new platform data.
Have a finished Reel to publish and measure?
Postdom publishes video you supply to TikTok, Instagram Reels, YouTube Shorts, LinkedIn, Facebook Reels, X, Snapchat Spotlight, Threads and Bluesky. It does not generate the video. After publishing, use the Postdom post ID to read stored performance with get_performance.