Instagram Insights API: account and media metrics

In short: how do you get Instagram stats through the API?

Login type: host and permissions

On the Facebook Login path, if the user's Page role was granted through Business Manager, Meta's docs also list ads_management and ads_read.

Account-level metrics

The list from Meta's current reference. Regular metrics are requested with period=day.

yesno

Every metric supports metric_type=total_value; reach also supports time_series. Demographics use period=lifetime plus a timeframe.

Media metrics by content type

The valid set depends on media_product_type. Request an unsupported metric and the Graph API rejects the whole call.

yesnoScroll the table sideways

likes and comments count organic interactions only. With Facebook Login you also get total_likes, total_comments and total_views, which include ad engagement.

2024–2025 changes: what was retired and what was added

This is exactly why code from older tutorials breaks.

For media created after July 2, 2024, impressions stopped working even earlier.

Demographics: who follows and who engages

Time ranges, delay and retention

Setting up stats collection in 5 steps

1. 1

   Check the account type

   The Instagram account must be Business or Creator. For Facebook Login, it's linked to a Facebook Page.

2. 2

   Request the insights permissions

   Instagram Login: instagram_business_basic and instagram_business_manage_insights. Facebook Login: instagram_basic, instagram_manage_insights, pages_read_engagement. Serving other people's accounts requires App Review for these.

3. 3

   Collect account metrics daily

   Request views, reach, accounts_engaged, total_interactions and friends with period=day, and store them every day.

4. 4

   Request media metrics by content type

   Look up media_product_type first (FEED, REELS, STORY), then request the matching set. Collect stories within 24 hours.

5. 5

   Pull demographics weekly or monthly

   Request follower_demographics with timeframe=this_month, once per breakdown, and store the result with a date.

Python: account, media and demographics

Facebook Login path: a Page token plus the Instagram account ID.

import asyncio, os
from datetime import date, timedelta
from socialift import Instagram

async def main() -> None:
    token = os.environ["PAGE_TOKEN"]
    ig_user_id = os.environ["IG_USER_ID"]
    async with Instagram.via_facebook(app_secret=os.environ["FACEBOOK_APP_SECRET"]) as ig:
        week = await ig.insights(
            token, ig_user_id=ig_user_id, since=date.today() - timedelta(days=7), until=date.today()
        )
        print(week["since"], week["until"], week["metrics"])

        for post in await ig.media(token, ig_user_id=ig_user_id, limit=5):
            print(post["id"], post["media_type"], await ig.media_insights(post["id"], token))

        demo = await ig.demographics(token, ig_user_id=ig_user_id)
        for cut, data in demo.items():
            print(cut, data["values"] if data["available"] else data["reason"])

asyncio.run(main())

What the Socialift SDK actually requests

Knowing which metrics each method asks for helps you build reports correctly.

Tips for a reporting pipeline

• ▸Use views instead of impressions and plays — update legacy dashboards.
• ▸Don't store an empty response as 0: it means "no data".
• ▸Re-fetch the last 48 hours daily — numbers may not be final yet.
• ▸Collect story insights within 24 hours.
• ▸Keep daily snapshots yourself and request long periods in chunks.
• ▸Handle missing permissions (PermissionError) separately from token problems (AuthError).