The content on this page has been translated from English into another language using AI. The AI translated content may contain errors, omissions, or unintended meanings. Since AI translated language may be inaccurate or unclear, you may refer to the original source content in English for this page to review the intended guidance.

API de Insights

Updated: 21 de mai de 2025

Oferece uma interface única e consistente para recuperar estatísticas de anúncios.

Detalhamentos: resultados de grupo.

Detalhamentos de ação: entenda a resposta dos detalhamentos de ação.\n

Trabalhos assíncronos: para solicitações com grandes resultados, use trabalhos assíncronos.\n

Limites e boas práticas: limites de chamada, filtragem e boas práticas.

Para receber dados de desempenho, configure seus anúncios para rastrear as métricas que são importantes para você.\n Para isso, você pode usar as tags de URL, o Pixel da Meta e a API de Conversões.\n

Antes de começar

Você precisará do seguinte:

A permissão ads_read.

Um app. Consulte Desenvolvimento de apps da Meta para saber mais.

Estatísticas de campanha

Para consultar as estatísticas de desempenho dos últimos 7 dias de uma campanha:\n

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

Para saber mais, consulte a referência de Insights sobre Anúncios.\n

Como fazer chamadas

A API de Insights está disponível como uma borda em qualquer objeto de anúncios.

Método da API
`act_<AD_ACCOUNT_ID>/insights`
`<CAMPAIGN_ID>/insights`
`<ADSET_ID>/insights`
`<AD_ID>/insights`

Solicitação\n

Você pode solicitar campos específicos com uma lista separada por vírgulas nos parâmetros fields. Por exemplo:\n

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/<AD_ID>/insights"

Resposta

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Níveis

Agregue os resultados em um nível de objeto definido. Isso elimina a duplicação dos dados automaticamente.

Solicitação\n

Por exemplo, obtenha os insights de uma campanha no nível do anúncio.\n

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/CAMPAIGN_ID/insights"

Resposta

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Se você não tiver acesso a todos os objetos do anúncio no nível solicitado, a chamada de insights não retornará dados. Por exemplo, ao solicitar insights com level definido como ad, se você não tiver acesso a um ou mais objetos desse tipo na conta de anúncios, a chamada de API retornará um erro de permissão.\n

Janelas de atribuição\n

A janela de atribuição de conversão oferece períodos de tempo que definem quando atribuímos o evento a um anúncio em um app da Meta. Para saber mais, consulte Sobre as janelas de atribuição no Gerenciador de Anúncios da Meta⁠. Mensuramos as ações que ocorrem quando acontece um evento de conversão e voltamos 1 e 7 dias no tempo. Para visualizar as ações designadas a janelas de atribuição diferentes, faça uma solicitação para /{ad-account-id}/insights. Se você não fornecer action_attribution_windows, usaremos 7d_click e informaremos em value.\n

Por exemplo, especifique action_attribution_windows, e "value" será fixado na janela de atribuição 7d_click.\n Faça uma solicitação para act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] e receba este resultado:\n

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

Expansão de campo

Solicite campos no nível do nó e por campos especificados na expansão de campo.\n

Solicitação\n

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/AD_ID"

Resposta

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Classificação

Classifique os resultados informando o parâmetro sort com {fieldname}_descending ou {fieldname}_ascending:

Solicitação\n

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/AD_SET_ID/insights"

Resposta

{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Rótulos de anúncios

Estatísticas de todos os rótulos cujos nomes são idênticos. Agregados em um único valor em um nível de objeto de anúncio. Consulte a referência de rótulos de anúncios para saber mais.

Solicitação\n

curl -G \
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/AD_OBJECT_ID/insights"

Resposta

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ],
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

Definição de cliques

Para entender melhor as métricas de cliques oferecidas pela Meta atualmente, leia as definições e o uso de cada uma abaixo:

Cliques no link, actions:link_click – o número de cliques em links do anúncio para selecionar destinos ou experiências dentro ou fora de propriedades da Meta. Consulte Cliques no link na Central de Ajuda de Anúncios⁠.

Cliques (todos), clicks – a métrica contabiliza diversos tipos de cliques no anúncio, inclusive determinadas interações com o contêiner de anúncios, links para outros destinos e links para experiências de anúncios expandidas. Consulte Cliques (todos) na Central de Ajuda de Anúncios⁠.

Objetos excluídos e arquivados

As unidades de anúncios podem ser DELETED ou ARCHIVED. As estatísticas de objetos excluídos ou arquivados aparecerão quando você consultar os respectivos objetos principais. Dessa forma, se você consultar impressions no nível do conjunto de anúncios, os resultados incluirão impressions de todos os anúncios do conjunto independentemente do estado de cada um deles (excluídos ou arquivados). Veja também Gerenciar o status de seu objeto de anúncio.

Porém, se você consultar usando filtros, a filtragem de status será aplicada por padrão para retornar apenas objetos ativos. Por isso, as estatísticas totais do nó principal poderão ser maiores que as estatísticas dos derivados.

No entanto, é possível obter as estatísticas de objetos ARCHIVED dos respectivos nós principais ao fornecer um parâmetro filtering adicional.

Solicitação\n

Para consultar as estatísticas de todos os anúncios ARCHIVED em uma conta de anúncios listadas uma a uma:

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/insights/"

Resposta

Observe que apenas os objetos arquivados são retornados nessa resposta.

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Insights sobre objetos excluídos

Você poderá consultar insights sobre objetos excluídos usando as respectivas identificações ou o filtro ad.effective_status.

Solicitação\n

Por exemplo, se você tiver a identificação do conjunto de anúncios:

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v25.0/AD_SET_ID"

Neste exemplo, consultamos com ad.effective_status:

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

Resposta

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Solução de problemas

Tempos-limite

Os problemas mais comuns que causam falha nesse ponto de extremidade são o excesso de solicitações e a ocorrência de tempos-limite:

Em solicitações /GET ou síncronas, é possível consultar erros de falta de memória ou de tempo-limite.

Em solicitações /POST ou assíncronas, é possível consultar erros de tempo-limite. Para solicitações assíncronas, pode ser que demore até uma hora para concluir uma solicitação, incluindo tentativas de repetição. Por exemplo, se você fizer uma consulta que tentar extrair grandes volumes de dados para muitos objetos de nível de anúncio.

Recomendações

Não há um limite explícito que indique quando ocorrerá uma falha na consulta. Quando o tempo limite for atingido, tente detalhar a consulta em consultas menores colocando filtros, como intervalo de datas.

O cálculo de métricas únicas é demorado. Tente consultar métricas exclusivas em uma chamada separada para melhorar o desempenho de métricas não exclusivas.

Limitação de volume

A API de Insights da Meta utiliza a limitação de volume para garantir uma experiência ideal de geração de relatórios a todos os nossos parceiros. Para mais informações e sugestões, consulte Limites e boas práticas da API de Insights.\n

Discrepância com o Gerenciador de Anúncios

A partir de 10 de junho de 2025, para reduzir discrepâncias com o Gerenciador de Anúncios da Meta, use_unified_attribution_setting e action_report_time parameters serão desconsiderados e as respostas da API imitarão as configurações do Gerenciador de Anúncios:

Os valores atribuídos (value) serão baseados nas configurações de atribuição no nível do conjunto de anúncios (semelhante a use_unified_attribution_setting=true), e as ações inline/no anúncio serão incluídas nos dados da janela de atribuição de 1d_click ou 1d_view. Depois dessa alteração, os dados de janela de atribuição inline independentes não serão retornados.

As ações serão registradas usando action_report_time=mixed: as ações na Meta (como cliques em links) usarão o tempo de relatórios baseado em impressões. Já as ações fora da Meta (como compras na web) aproveitarão o tempo de relatórios baseado em conversões.

Os comportamentos padrão da API e do Gerenciador de Anúncios são diferentes. Se você quiser observar o mesmo comportamento do Gerenciador de Anúncios, defina o campo use_unified_attribution_setting como verdadeiro.

Saiba mais

Ad Account Insights\n

Insights sobre campanhas de anúncios\n

Insights sobre o conjunto de anúncios\n

Insights sobre anúncios\n

Essa API cobre apenas os pontos de extremidade da lista acima.\n Se você pretende incluir relatórios da Meta na sua solução, consulte os Termos de Serviço e as Políticas do Desenvolvedor relacionadas à API de Marketing.

Você achou esta página útil?