Dados demográficos de seguidores do Instagram pela API
O endpoint de insights da conta retorna os dados demográficos dos seguidores com metric=follower_demographics, period=lifetime, metric_type=total_value, um timeframe e um detalhamento por idade, gênero, cidade ou país. engaged_audience_demographics faz o mesmo para as contas que interagiram com o conteúdo. A Meta retorna apenas os 45 primeiros valores; os dados de seguidores exigem 100 seguidores, e os dados da audiência engajada exigem 100 interações no timeframe.
O easyCoexistence lê dados demográficos de seguidores e da audiência engajada do Instagram com get_social_insights, para que o Claude, o ChatGPT ou seu próprio código possa perguntar quais países, cidades ou faixas etárias seguem a conta e obter os números da Meta para a conta conectada.
Abaixo disso, follower_demographics não é retornado para a conta.
Interações necessárias no timeframe antes que engaged_audience_demographics seja retornado.
Métricas demográficas retornam apenas os 45 melhores resultados, então cidades e países menores ficam de fora.
Quando last_14_days, last_30_days, last_90_days e prev_month pararam de funcionar para engaged_audience_demographics em todas as versões.
Por quanto tempo os dados por trás das métricas da conta podem sofrer atraso.
Quais métricas demográficas existem?
Duas no material de referência de insights da conta da Meta, ambas lidas com GET /<IG_ID>/insights, e dois conjuntos mais antigos que códigos antigos ainda solicitam:
follower_demographics: as características demográficas dos seguidores da conta.engaged_audience_demographics: o mesmo para a audiência engajada, as contas que interagiram com o conteúdo.- Ambas: period lifetime,
metric_typetotal_value, um timeframe e um detalhamento por idade, cidade, país ou gênero. audience_gender_age,audience_locale,audience_countryeaudience_city: descontinuadas em 11 de dezembro de 2023.reached_audience_demographics: citada no changelog de 2024 da Meta, mas ausente da tabela atual de métricas.
Como solicitar dados demográficos de seguidores?
Com a métrica, period=lifetime, metric_type=total_value, um timeframe e um detalhamento. timeframe substitui since e until, que as métricas demográficas não suportam, e é obrigatório. Com o Instagram Login, o token precisa de instagram_business_basic e instagram_business_manage_insights, e a chamada vai para 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>Como é a resposta?
As contagens ficam em total_value.breakdowns. dimension_keys indica o timeframe e o detalhamento solicitados, e cada resultado combina dimension_values, o timeframe e um valor do detalhamento, com uma contagem. O exemplo da Meta, para a audiência engajada por país, retorna países como códigos de duas letras, como US e 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"
}
]
}Quais timeframes funcionam?
A referência da Meta lista last_14_days, last_30_days, last_90_days, prev_month, this_month e this_week para ambas as métricas e, para a audiência engajada, descreve this_month como os últimos 30 dias e this_week como os últimos 7. Para engaged_audience_demographics, os quatro primeiros pararam de funcionar a partir da v20.0 e em todas as versões em 19 de agosto de 2024, então use this_week ou this_month. Essa entrada do changelog não cita follower_demographics.
Quais limites mínimos e restrições se aplicam?
A referência de insights da conta da Meta define estas regras para métricas demográficas:
follower_demographicsnão é retornado para uma conta com menos de 100 seguidores.engaged_audience_demographicsnão é retornado com menos de 100 interações no timeframe.- Só voltam os 45 melhores resultados, então cidades e países menores ficam de fora.
- Só são contados os espectadores com dados demográficos, então os valores podem somar menos que o número de seguidores.
- Dados ausentes retornam um conjunto vazio, não 0, e os dados podem atrasar até 48 horas.
- Um detalhamento que a métrica solicitada não suporta faz toda a chamada falhar com An unknown error has occurred.
Dados demográficos funcionam com o Instagram Login?
Sim. A Meta abriu insights de conta e de mídia para apps com Instagram Login em 21 de janeiro de 2025, e a referência de insights da conta lista o Instagram Login com as permissões instagram_business_basic e instagram_business_manage_insights e graph.instagram.com como host. A conta precisa ser uma conta comercial ou de criador, como exige a Plataforma do Instagram da Meta.
Como o get_social_insights lê dados demográficos?
Com metrics definido como follower_demographics ou engaged_audience_demographics, period definido como lifetime e params contendo timeframe, breakdown e metric_type. O easyCoexistence chama GET /<IG_ID>/insights para a conta conectada com o token dela e devolve a resposta da Meta, para que o Claude ou o ChatGPT possa dizer quais países, cidades ou faixas etárias seguem a conta.
{
"account_id": "<ACCOUNT_ID>",
"metrics": ["follower_demographics"],
"period": "lifetime",
"params": {
"timeframe": "this_month",
"breakdown": "age",
"metric_type": "total_value"
}
}Erros comuns
- Passar since e until. Métricas demográficas não suportam esses parâmetros: timeframe define o intervalo, e é obrigatório.
- Usar last_30_days ou last_90_days para a audiência engajada. Esses timeframes pararam de funcionar para engaged_audience_demographics em todas as versões em 19 de agosto de 2024.
- Somar um detalhamento para obter a contagem de seguidores. Só são contados espectadores com dados demográficos e só voltam os 45 primeiros valores, então a soma fica abaixo.
- Esperar dados de uma conta pequena. Dados demográficos de seguidores exigem 100 seguidores, e a audiência engajada, 100 interações no timeframe.
De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os 3 primeiros dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Quantos seguidores uma conta do Instagram precisa para ter dados demográficos?
100. Abaixo disso, a Meta não retorna follower_demographics; engaged_audience_demographics exige 100 interações no timeframe.
Por que o Instagram retorna apenas 45 cidades?
As métricas demográficas da Meta retornam somente os 45 melhores resultados, então cidades e países menores ficam de fora.
O que substituiu audience_gender_age na API do Instagram?
follower_demographics, com detalhamento por idade, gênero, cidade ou país. A Meta descontinuou audience_gender_age, audience_locale, audience_country e audience_city em 11 de dezembro de 2023.
Posso usar since e until com follower_demographics?
Não. Métricas demográficas não suportam since e until; o parâmetro timeframe define o intervalo, e é obrigatório.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em