Pular para o conteúdo principal
POST
Obtenha análises e dados demográficos do perfil social de um usuário, como impressões, visualizações e seguidores. Atualmente disponível para Bluesky, Facebook Pages, Google My Business, Instagram, LinkedIn, Pinterest, Reddit, Snapchat, Threads, TikTok, X/Twitter e YouTube.
Facebook: algumas métricas de alcance e vídeo foram descontinuadas pela Meta (15 de junho de 2026). A Meta removeu as métricas de Insights de impressões únicas e visualizações únicas de vídeo de 3 segundos em todas as versões da Graph API, portanto o objeto analytics do Facebook não retorna mais a família pagePostsImpressions* (pagePostsImpressions, pagePostsImpressionsPaid, pagePostsImpressionsUnique, pagePostsImpressionsOrganicUnique, pagePostsImpressionsViral*, pagePostsImpressionsNonviral*, pagePostsServedImpressionsOrganicUnique) nem pageVideoViewsUnique. Use pageMediaView para alcance (um sucessor Total Unique Media Views está planejado). pagePostEngagements, pageVideoViews e pageVideoViewsPaid não são afetados. Referência: Próximas mudanças na API — 15 de junho de 2026.
  • Análises do Facebook Page estão disponíveis apenas em Pages com 100 ou mais curtidas, como dados demográficos. O Facebook normalmente atualiza suas métricas uma vez a cada 24 horas.
  • O Instagram pode levar até 48 horas para calcular os dados analíticos. Análises de contagem de seguidores não estão disponíveis com menos de 100 seguidores. Métricas demográficas retornam apenas os 45 melhores desempenhos; apenas espectadores para os quais temos dados demográficos são usados nos cálculos de métricas demográficas; e dados demográficos não são retornados se o usuário do Instagram tiver menos de 100 engajamentos nos últimos 30 dias.
  • Ao obter análises sociais do Instagram, informações demográficas podem não aparecer na resposta para métricas específicas. Informações demográficas aparecerão quando as métricas tiverem mais de 100 pessoas em cada desdobramento. Consulte Aviso sobre dados demográficos das análises do Instagram para mais informações.
  • O LinkedIn suporta análises tanto de Company Page quanto de perfil pessoal (de membro). Para perfis pessoais, o objeto analytics inclui um followersCount vitalício, crescimento diário de seguidores em followersDaily[] e métricas agregadas de publicação (impressionCount, uniqueImpressionsCount, likeCount, commentCount, shareCount). Os totais count do LinkedIn são eventualmente consistentes, mas não imediatamente consistentes, e podem levar até 24-48 horas em alguns casos. Os agregados shareCount, likeCount e commentCount para perfis pessoais são best-effort e podem diferir ligeiramente dos números mostrados na UI do LinkedIn.
  • O TikTok pode levar de 24 a 48 horas para atualizar seus dados analíticos, como visualizações de vídeo, dados demográficos, curtidas, compartilhamentos e comentários.
  • Consulte o endpoint de análises de publicação para informações adicionais.

Parâmetros de cabeçalho

Parâmetros do corpo

platforms
array
obrigatório
Plataformas de rede social para obter análises. Aceita um array de strings com os valores:
quarters
integer
Especifica quantos trimestres de dados históricos retornar. Um trimestre é:
  • 85 dias para Facebook
  • 90 dias para Instagram, TikTok e YouTube
  • 90 dias para Snapchat (limitado a 1 trimestre / 90 dias no máximo devido às limitações da API do Snapchat)
Disponível para as plataformas Facebook, Instagram, Snapchat, TikTok e YouTube. Valores válidos: 1–4. Apenas valores maiores que 0 ativam o filtro por data.Filtro por data (Instagram e TikTok): O filtro por data fica ativo quando daily=true OU quarters > 0. Se nem daily nem quarters for fornecido, dados de todo o período são retornados sem filtro de data aplicado.Observação: quarters: 0 agora é tratado como sem intervalo de datas (dados de todo o período). Anteriormente, quarters: 0 era tratado como quarters: 1.
daily
boolean
padrão:false
Quando definido como true, retorna dados analíticos como valores diários de série temporal em vez de totais agregados. Esta opção só está disponível para as plataformas Facebook, Instagram, Snapchat, TikTok e YouTube. Devido ao maior tamanho dos dados, recomenda-se usar compressão.Para Instagram e TikTok, definir daily=true também ativa o filtro por data usando uma janela de trimestres mais curta padrão.Reach do Instagram: Com daily=true, a resposta do Instagram retorna um objeto reach aninhado (contendo period e uma série temporal values) em vez do campo escalar reachCount que é retornado no modo não diário.
period60Days
boolean
padrão:false
Para análises do TikTok, quando definido como true, retorna apenas os totais agregados de 60 dias para comentários, compartilhamentos e visualizações (commentCountTotal, shareCountTotal, viewCountTotal). Isso oferece tempos de resposta mais rápidos em comparação com a obtenção do histórico completo de análises. Observação: não use este parâmetro em conjunto com daily=true, pois são incompatíveis.Importante: a partir de 1º de março de 2025, o TikTok passou a usar totais de 60 dias. A partir de abril de 2026, o TikTok usa filtro por data baseado em trimestres — use o parâmetro quarters para controlar a janela de datas (por exemplo, quarters: 1 = 90 dias, quarters: 2 = 180 dias). Consulte próximas mudanças para detalhes.
youtube
object
Opções específicas de plataforma para análises do YouTube.lifetime (boolean, padrão: false): Quando definido como true, inclui lifetimeLikes na resposta - a soma de curtidas em todos os vídeos públicos do canal. Isso é calculado buscando todos os vídeos e somando suas contagens de curtidas, portanto pode levar mais tempo para canais com muitos vídeos.Limite: Canais com mais de 1.000 vídeos retornarão lifetimeLikes: null e um aviso no array warnings de nível superior. Isso previne uso excessivo da API.Cache: Por canal, com TTLs mais curtos para resultados não bem-sucedidos, para que retentativas percebam mudanças de estado rapidamente:
  • Valor bem-sucedido de lifetimeLikes: 24 horas.
  • Bailout de 1.000 vídeos (aviso code: 445): 1 hora — curto o suficiente para que um canal que exclui vídeos para ficar abaixo do limite não precise esperar um dia inteiro por um valor real.
  • Falhas transitórias da YouTube Data API (aviso code: 446): não fica em cache — a próxima requisição tenta novamente.
Observação: Vídeos excluídos ou privados são excluídos da soma, portanto o total pode diferir do total “verdadeiro” de curtidas vitalícias para canais que removeram vídeos.Exemplo de requisição:
userId
string
Apenas X/Twitter. Este parâmetro permite obter publicações de um usuário específico do X/Twitter pelo ID numérico, em vez da sua conta vinculada.Por exemplo, para obter todas as publicações do handle @Google, você usaria o userId numérico dele: 20536157.Você pode encontrar o userId numérico de qualquer usuário do X/Twitter usando o endpoint Brands Get User.Observação: use apenas o API KEY no cabeçalho para fazer esta requisição. Não inclua o Profile Key.
userName
string
Apenas X/Twitter. Este parâmetro permite obter publicações de um usuário específico do X/Twitter pelo handle, em vez da sua conta vinculada.Por exemplo, para obter todas as publicações do handle @Google.Observação: use apenas o API KEY no cabeçalho para fazer esta requisição. Não inclua o Profile Key.
Quando métricas cumulativas (por exemplo, seguidores, curtidas) estão temporariamente indisponíveis na rede social, a API as preenche automaticamente a partir de dados armazenados. Dois campos opcionais podem aparecer no objeto analytics por plataforma:
  • backfilledFrom (string, ISO 8601) — Presente quando uma ou mais métricas cumulativas foram substituídas por dados armazenados. O timestamp indica quando os dados armazenados foram atualizados pela última vez.
  • recoveredFrom (string, ISO 8601) — Presente quando toda a resposta de análises foi recuperada de dados armazenados devido a uma falha completa da API. O timestamp indica quando os dados armazenados foram atualizados pela última vez.
Dados armazenados com mais de 4 dias são considerados desatualizados e não serão usados para backfill ou recovery.reactions do LinkedIn: A métrica cumulativa reactions no nível de publicação (um objeto de contagens de reações por tipo) está sujeita a este backfill de apenas-vazio. Quando o LinkedIn aplica limite de taxa na busca de reações, o valor é mantido a partir do último snapshot bem-sucedido — e backfilledFrom é definido para o timestamp desse snapshot — em vez de regredir para vazio.
Análises pessoais (de membro) do LinkedIn — revinculação obrigatória. Perfis pessoais do LinkedIn vinculados antes do lançamento das análises de membro não têm os scopes de análises necessários. Requisições de análises sociais para esses perfis retornam o código de erro 475 (“re-link your LinkedIn profile to enable analytics”). O dono da conta deve revincular seu perfil do LinkedIn na página Social Accounts para conceder os novos scopes. Aguarde alguns minutos após a revinculação para que o code 475 deixe de aparecer (Ayrshare e LinkedIn armazenam brevemente o estado da permissão em cache, tipicamente ~5-10 minutos). A publicação não é afetada.
warnings (array de objetos, campo opcional de nível superior) — Presente apenas quando o Ayrshare precisa informar o chamador sobre uma condição não fatal (por exemplo, um cálculo opt-in foi ignorado). Ausente da resposta quando não há nada a avisar.Cada entrada é um objeto estruturado, não uma string de formato livre:
CampoTipoDescrição
actionstringO contexto da operação que produziu o aviso (por exemplo, "analytics").
statusstringSempre "warning" para entradas do array warnings.
codenumberCódigo de aviso estável do Ayrshare. Seguro para comparar no código cliente.
messagestringDescrição legível por humanos.
detailsstringContexto adicional opcional específico desta instância de aviso.
Códigos de aviso conhecidos:
  • 445lifetimeLikes ignorado porque o canal do YouTube excede o limite de 1.000 vídeos.
  • 446lifetimeLikes indisponível porque a YouTube Data API retornou erros para a playlist de uploads ou para cada batch de videos.list.