Instagram follower demographics through the API
Instagram's account insights endpoint returns follower demographics with metric=follower_demographics, period=lifetime, metric_type=total_value, a timeframe and a breakdown of age, gender, city or country. engaged_audience_demographics does the same for accounts that engaged with the content. Meta returns the top 45 values only; follower data needs 100 followers, and engaged data 100 engagements in the timeframe.
easyCoexistence reads Instagram follower and engaged-audience demographics with get_social_insights, so Claude, ChatGPT or your own code can ask which countries, cities or age groups follow the account and get Meta's numbers for the connected account.
Below this, follower_demographics is not returned for the account.
Needed in the timeframe before engaged_audience_demographics is returned.
Demographic metrics return only the top 45 performers, so smaller cities and countries drop out.
When last_14_days, last_30_days, last_90_days and prev_month stopped working for engaged_audience_demographics in every version.
How long the data behind account metrics can be delayed.
Which demographic metrics are there?
Two in Meta's account insights reference, both read with GET /<IG_ID>/insights, and two older sets that old code still asks for:
follower_demographics: the demographic characteristics of the account's followers.engaged_audience_demographics: the same for the engaged audience, the accounts that interacted with its content.- Both: period lifetime,
metric_typetotal_value, a timeframe, and a breakdown of age, city, country or gender. audience_gender_age,audience_locale,audience_countryandaudience_city: retired on 11 December 2023.reached_audience_demographics: named in Meta's 2024 changelog but absent from its current metrics table.
How do you request follower demographics?
With the metric, period=lifetime, metric_type=total_value, a timeframe and one breakdown. timeframe replaces since and until, which demographic metrics do not support, and it is required. With Instagram Login the token needs instagram_business_basic and instagram_business_manage_insights, and the call goes to graph.instagram.com:
GET https://graph.instagram.com/<IG_ID>/insights
?metric=follower_demographics
&period=lifetime
&timeframe=this_month
&breakdown=country
&metric_type=total_value
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>What does the response look like?
Counts in total_value.breakdowns. dimension_keys names the timeframe and the breakdown requested, and each result pairs dimension_values, the timeframe and one value of the breakdown, with a count. Meta's sample, for the engaged audience by country, returns countries as two-letter codes such as US and ES:
{
"data": [
{
"name": "follower_demographics",
"period": "lifetime",
"title": "<TITLE>",
"description": "<DESCRIPTION>",
"total_value": {
"breakdowns": [
{
"dimension_keys": ["timeframe", "country"],
"results": [
{ "dimension_values": ["<TIMEFRAME>", "<COUNTRY_CODE>"], "value": <COUNT> },
{ "dimension_values": ["<TIMEFRAME>", "<COUNTRY_CODE>"], "value": <COUNT> }
]
}
]
},
"id": "<IG_ID>/insights/follower_demographics/lifetime"
}
]
}Which timeframes work?
Meta's reference lists last_14_days, last_30_days, last_90_days, prev_month, this_month and this_week for both metrics and, for the engaged audience, describes this_month as the last 30 days and this_week as the last 7. For engaged_audience_demographics the first four stopped working from v20.0 and in every version on 19 August 2024, so use this_week or this_month; that changelog entry does not name follower_demographics.
What thresholds and limits apply?
Meta's account insights reference sets these rules for demographic metrics:
follower_demographicsis not returned for an account with fewer than 100 followers.engaged_audience_demographicsis not returned with fewer than 100 engagements in the timeframe.- Only the top 45 performers come back, so smaller cities and countries drop out.
- Only viewers with demographic data are counted, so the values can sum to less than the follower count.
- Missing data returns an empty set, not 0, and data can lag by up to 48 hours.
- A breakdown that a requested metric does not support fails the whole call with An unknown error has occurred.
Do demographics work with Instagram Login?
Yes. Meta opened account and media insights to Instagram Login apps on 21 January 2025, and its account insights reference lists Instagram Login with the instagram_business_basic and instagram_business_manage_insights permissions and graph.instagram.com as the host. The account has to be a business or creator account, as Meta's Instagram Platform requires.
How does get_social_insights read demographics?
With metrics set to follower_demographics or engaged_audience_demographics, period set to lifetime and params carrying timeframe, breakdown and metric_type. easyCoexistence calls GET /<IG_ID>/insights for the connected account with its token and returns Meta's response, so Claude or ChatGPT can say which countries, cities or age groups follow the account.
{
"account_id": "<ACCOUNT_ID>",
"metrics": ["follower_demographics"],
"period": "lifetime",
"params": {
"timeframe": "this_month",
"breakdown": "age",
"metric_type": "total_value"
}
}Common mistakes
- Passing since and until. Demographic metrics do not support them: timeframe sets the range, and it is required.
- Using last_30_days or last_90_days for the engaged audience. Those timeframes stopped working for engaged_audience_demographics in every version on 19 August 2024.
- Summing a breakdown to get the follower count. Only viewers with demographic data are counted and only the top 45 values return, so the sum falls short.
- Expecting data from a small account. Follower demographics need 100 followers, and the engaged audience 100 engagements in the timeframe.
US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
How many followers does an Instagram account need for demographics?
100. Below that, Meta does not return follower_demographics; engaged_audience_demographics needs 100 engagements in the timeframe.
Why does Instagram return only 45 cities?
Meta's demographic metrics return the top 45 performers only, so smaller cities and countries are left out.
What replaced audience_gender_age in the Instagram API?
follower_demographics, with a breakdown of age, gender, city or country. Meta retired audience_gender_age, audience_locale, audience_country and audience_city on 11 December 2023.
Can I use since and until with follower_demographics?
No. Demographic metrics do not support since and until; the timeframe parameter sets the range instead, and it is required.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on