The Instagram insights API: which metrics you get, and how it fails

The Instagram insights API is two endpoints — one for a media object, one for the account — and almost all of the difficulty is in knowing which metric names each will accept. Ask for a name the object does not support and you do not get a partial answer. You get an error, and nothing.

This is what the endpoints return in practice, taken from the connector that calls them daily and from Meta’s own reference.

Which Instagram API are you actually calling?

There are two, they have different hosts, and the difference decides your whole integration. Meta’s documentation states it plainly: Instagram API with Instagram Login is served from graph.instagram.com, and Instagram API with Facebook Login is served from graph.facebook.com.

Instagram Login for Business lets a Business or Creator account authorize your app directly, with no Facebook Page and no Business Manager in the path. That removes the single most common reason an onboarding flow fails — the customer has an Instagram account but no linked Page, or no permission on the Page that is linked.

If you are starting now, start on graph.instagram.com. The Facebook Login path still exists and still works, but it asks your customer to own and grant access to a Page they may not have, which is a support conversation you have to have before any data moves.

Which metrics does Instagram serve for a post or reel?

Media insights are a lifetime-to-date count, not a time series: you ask today and get the total so far. If you want a history you have to record the answer yourself, every day, because Instagram will not give you yesterday’s value tomorrow.

Account metrics are a different list entirely, and they are a genuine time series: period=day with since and until gives one value per day. The ones that matter are reach, views, accounts_engaged, total_interactions, likes, comments, shares, saves, replies and profile_links_taps. Note saves here against saved on media — same concept, two spellings, one endpoint apart.

Account insights need metric_type=total_value as well as period=day. Without it the endpoint returns a differently-shaped payload, and code written against one shape silently reads nothing from the other — the request succeeds and every value comes back empty.

What happens when you request a metric the media does not support?

The entire request fails with error code 100. Not a partial result with the unsupported name omitted — nothing at all, including the eight metrics you asked for that were perfectly valid.

This is the exact opposite of how Meta’s ads Insights endpoint behaves. There, a field the API will not serve is quietly left out of the response and everything else comes back. Two APIs from the same company, with opposite failure modes, which means the correct client strategy for each is also opposite.

For Meta Ads the right move is to ask for the full field list every time and let the API omit what it will not serve, so a field that becomes available later arrives without a code change. For Instagram the same approach costs you the whole response. What works instead is a fallback:

1. Ask for the full set for this product type.
2. On error 100, retry with a core set known to work almost everywhere — reach, saved, shares, total_interactions, views.
3. Probe the remaining names one at a time, and remember which ones failed, keyed by media_product_type.

The memory is the part that matters. Without it, every sync re-discovers the same unsupported metric on every reel in the account, which turns one failed request into thousands and pushes you toward a rate limit for no information at all.

Why a metric can be unsupported at all

Sometimes it is the media type — watch-time metrics on a still image are meaningless. But Meta also documents a rule that catches people out: *“Some metrics are not available on Instagram accounts with fewer than 100 followers.”*

So the same code, against the same media type, works for one customer and fails for another, and the difference is an audience size you did not ask about. Any error taxonomy that assumes a metric is either supported or not — rather than supported *for this account* — will be wrong for every small account you onboard.

How far back does Instagram insights data go?

Meta’s insights documentation states: *“User Metrics data is stored for up to 90 days.”* Everything older than that is gone — not summarized, not available at a coarser grain. If you want a year of account history, the only way to have it is to have been recording it for a year.

That single sentence is the strongest argument for connecting an account before you need the data rather than when you need it. A backfill run today can reach back ninety days and no further, and a customer who connects in March cannot be shown last December however much they want it.

Media metrics behave differently, and worse in one way: because they are lifetime-to-date counts rather than a series, there is no backfill at all. The first day you record a post is the first day you have for it. Everything before that exists only as the single cumulative number the API happens to report now.

What changed recently?

Instagram’s insights surface moves, and it mostly moves by addition. In December 2025 Meta announced *“five new metrics to the Insights endpoint, alongside an update to the existing views metric”*:

• Reels skip rate — the percentage of views where a viewer skips within the first three seconds.
• Repost counts for media — how often an individual post is reposted.
• Repost counts at account level — the same, aggregated.
• Instagram profile visits in the Marketing API — visits to an advertiser’s profile after an ad interaction.
• Crossposted reel views — split into crossposted_views and facebook_views.

The lesson is less about these five names than about the shape of the problem: a metric list hardcoded a year ago is a metric list that is now missing data Meta is willing to give you, and nothing will tell you. There is no deprecation warning for a metric you never asked for.

What this means if you are building it yourself

1. Pick `graph.instagram.com` and Instagram Login for Business unless you have a specific reason to need the Page. It removes the commonest onboarding failure.
2. Record media metrics daily. They are cumulative counts with no history, so the series only exists if you build it.
3. Connect accounts early. The 90-day account window is a hard floor on how much past you can ever recover.
4. Build the error-100 fallback, and cache what it learns per media_product_type — but exclude subcode 33, which is a permissions problem wearing an unsupported-metric costume.
5. Re-read the changelog on a schedule. New metrics arrive silently and a static list quietly stops being complete.
6. Normalize names once, in one file. total_interactions and saved are the two that will otherwise end up duplicated under friendlier names.

If you would rather not maintain that, it is what the Instagram connector does: daily capture of every post and reel, the account series, and the fallback that keeps one unsupported name from costing a whole sync.