API de estadísticas

Ofrece una interfaz exclusiva y coherente que permite recuperar estadísticas de anuncios.

Desgloses: resultados de grupos
Desgloses por acción: se explica la respuesta a partir de desgloses por acción.
Trabajos asincrónicos: se usan para solicitudes que incluyen resultados de gran volumen.
Límites y prácticas recomendadas: límites de llamadas, filtros y prácticas recomendadas.

Para poder obtener datos sobre el rendimiento de tus anuncios, debes configurar que se realice el seguimiento de las métricas que te interesa obtener de estos anuncios. Para eso, puedes utilizar etiquetas de URL, el píxel de Meta y la API de conversiones.

Actualizaciones de iOS 14.5

Como respuesta a la nueva política de Apple, anunciamos cambios importantes que afectarán a los intervalos de atribución.

Para obtener más información sobre cómo influirán los requisitos de iOS 14.5 de Apple en los anuncios de Facebook, consulta los artículos del servicio de ayuda para empresas y nuestro registro de cambios:

Puntos de conexión afectados

GET /{ad-account-id}/insights
GET /{ad-id}/insights
GET /{ad-set-id}/insights
GET /{campaign-id}/insights
POST /{ad-account-id}/insights
POST /{ad-id}/insights
POST /{ad-set-id}/insights
POST /{campaign-id}/insights

Antes de empezar

Necesitarás lo siguiente:

El permiso ads_read.
Una app. Consulta Desarrollo de apps de Meta para obtener más información.

Estadísticas de la campaña

Para obtener las estadísticas del rendimiento de una campaña durante los últimos siete días:

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

Si quieres obtener más información, consulta Estadísticas de anuncios, referencia.

Realizar llamadas

La API de estadísticas se encuentra disponible como un perímetro en cualquier objeto de anuncio.

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

Solicitud

Puedes solicitar campos específicos con una lista separada por comas en los parámetros fields. Por ejemplo:

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

Respuesta

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

Niveles

Agrega resultados en un nivel de objeto definido, lo que deduplica los datos de manera automática.

Solicitud

Por ejemplo, obtén las estadísticas de una campaña en el nivel del anuncio.

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

Respuesta

{
  "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"
    }
  }
}

Si no tienes acceso a todos los objetos de anuncio en el nivel solicitado, la llamada de estadísticas no devuelve ningún dato. Por ejemplo, al solicitar estadísticas con level establecido en ad, si no tienes acceso a un objeto de anuncio o más en la cuenta publicitaria, esta llamada a la API devolverá un error de permiso.

Intervalos de atribución

Actualizaciones para iOS 14 y versiones posteriores

Si action_attribution_windows no está definido, los valores de atribución predeterminados son 7d_click y 1d_view. Cuando empiece a aplicarse la nueva política, las opciones de 28 días tras la visualización dejarán de estar disponibles y no devolverán datos.
En el caso de los anuncios antiguos inactivos que tengan un valor de intervalo de 28 días, devolveremos los datos.
En los intervalos predeterminados o del nivel de la cuenta, el valor se establecerá en siete días después de la aplicación de las políticas.
El campo use_account_attribution_setting quedó obsoleto. Estas solicitudes se cambiarán a las opciones predeterminadas 7d_click y 1d_view de action_attribution_windows.

Visita el registro de cambios importantes para obtener más información sobre las modificaciones introducidas a causa de la versión 14 de iOS.

El intervalo de atribución de conversiones proporciona períodos que definen el momento en que atribuimos un evento a un anuncio en una app de Meta. Para obtener información general, consulta el servicio de ayuda de Meta para empresas, Información sobre los intervalos de atribución. Medimos las acciones que tienen lugar cuando ocurre un evento de conversión y analizamos períodos de un día y siete días. Para ver las acciones atribuidas a diferentes intervalos de atribución, haz una solicitud a /{ad-account-id}/insights. Si no proporcionas action_attribution_windows, usamos 7d_click y mostramos el resultado en value.

Por ejemplo, especifica action_attribution_windows, y el "value" se establecerá en intervalos de atribución de 7d_click. Envía una solicitud a act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] y obtén este resultado:

"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
},

Expansión de campos

Solicita campos en el nivel del nodo y en función de los campos especificados en la expansión de campos.

Solicitud

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

Respuesta

{
  "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"
      }
    }
  }
}

Ordenar

Para ordenar los resultados, proporciona el parámetro sort con {fieldname}_descending o {fieldname}_ascending:

Solicitud

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

Respuesta


{
  "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"
    }
  }
}

Etiquetas de anuncios

Obtén estadísticas de todas las etiquetas cuyos nombres sean idénticos. Estas se agregan a un valor único en un nivel de objeto de anuncio. Consulta la Referencia de etiquetas de anuncios para obtener más información.

Solicitud

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/v19.0/AD_OBJECT_ID/insights"

Respuesta

{
  "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==",
    }
  }
}

Definición de clics

Para comprender mejor las métricas relacionadas con clics que Meta ofrece en la actualidad, lee las definiciones y los usos de cada una de ellas a continuación:

Clics en el enlace, actions:link_click: número de clics en enlaces de anuncios que dirigen a determinadas páginas de destino o experiencias, tanto en propiedades de Meta como fuera de ellas. Consulta "Clics en el enlace" en el servicio de ayuda para anunciantes.
Clics (todos), clicks: la métrica muestra varios tipos de clics en el anuncio, entre ellos, algunos tipos de interacciones con el contenedor del anuncio, enlaces a otros destinos y enlaces para proporcionar una experiencia expandida del anuncio. Consulta "Clics (todos)" en el servicio de ayuda para anunciantes.

Objetos eliminados y archivados

Los anuncios pueden estar DELETED o ARCHIVED. Las estadísticas de los objetos eliminados o archivados se mostrarán cuando consultes los objetos principales. Esto significa que, si consultas impressions en el nivel del conjunto de anuncios, los resultados incluirán impressions de todos los anuncios del conjunto, independientemente de si los anuncios están eliminados o archivados. Consulta también Práctica recomendada para almacenar y recuperar objetos de anuncio.

Sin embargo, si realizas consultas con filtrado, el filtrado de estado se aplicará de forma predeterminada para que devuelva solo objetos activos. Como consecuencia, las estadísticas totales del nodo principal pueden ser mayores que las estadísticas de los nodos secundarios.

Puedes obtener las estadísticas de los objetos ARCHIVED a partir de sus nodos principales al proporcionar un parámetro filtering adicional.

Solicitud

Para obtener las estadísticas de todos los anuncios ARCHIVED en una cuenta publicitaria enumerados uno a uno:

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

Respuesta

Ten en cuenta que esta respuesta te muestra solo los objetos archivados.

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

Estadísticas de objetos eliminados

Puedes consultar estadísticas de objetos eliminados si cuentas con sus identificadores o mediante el filtro ad.effective_status.

Solicitud

Por ejemplo, si tienes el identificador del conjunto de anuncios:

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

En este ejemplo, la consulta se realiza con 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"]}]

Respuesta

{
  "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"
      }
    }
  }
}

Solución de problemas

Errores de tiempo de espera agotado

Los problemas más comunes que ocasionan fallas en este punto de conexión se deben a la cantidad excesiva de solicitudes y errores de tiempo de espera agotado.

En solicitudes sincronizadas o /GET, puede haber errores de tiempo de espera agotado o falta de espacio en la memoria.
En solicitudes asincrónicas o /POST, es posible que haya errores de tiempo de espera agotado. En el caso de las solicitudes asincrónicas, es posible que lleve una hora completar una solicitud, incluidos los reintentos. Por ejemplo, si realizas una consulta mediante la que intentas obtener un gran volumen de datos de muchos objetos en el nivel del anuncio.

Recomendaciones

No existe un límite explícito sobre cuándo se producirá una falla en la consulta. Cuando se agota el tiempo de espera, desglosa la consulta en consultas más breves mediante filtros como intervalo de fechas.
Calcular los resultados únicos demanda mucho tiempo. Consulta los resultados únicos en una llamada independiente para mejorar el rendimiento de los resultados que no son únicos.

Limitación de frecuencia

La API de estadísticas de Meta usa la limitación de frecuencia a fin de garantizar una experiencia de informes óptima para todos nuestros socios. Para obtener más información y sugerencias, consulta Límites y prácticas recomendadas de nuestra API de estadísticas.

Discrepancia con el administrador de anuncios

El comportamiento predeterminado de la API es diferente del comportamiento predeterminado en el administrador de anuncios. Si quieres observar el mismo comportamiento que en el administrador de anuncios, fija el campo use_account_attribution_setting en "true".

Más información

Esta API no abarca puntos de conexión que no figuren en la lista anterior. Si pretendes incluir informes de Meta en tu solución, consulta las Condiciones de la plataforma de Meta y las Políticas para desarrolladores de la API de marketing.