API de insights

Proporciona una interfaz única y coherente para recuperar las estadísticas de los anuncios.

• Desgloses: resultados de grupo.
• Desgloses de acciones: comprende la respuesta de los desgloses de acciones.
• Trabajos asíncronos: para solicitudes con muchos resultados, utiliza trabajos asíncronos.
• Límites y prácticas recomendadas: límites de llamada, filtros y prácticas recomendadas.

Para poder obtener los datos sobre el rendimiento de tu anuncio, debes configurar los anuncios para que lleven a cabo el seguimiento de los resultados que te interesan. Para ello, puedes utilizar etiquetas de URL, el píxel de Meta y la API de conversiones.

Antes de empezar

Necesitarás lo siguiente:

• El permiso ads_read.
• Una aplicación. Consulta Desarrollo de aplicaciones 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 correspondiente a 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"

Para obtener más información, consulta Insights de anuncios, Referencia.

Realización de llamadas

La API de insights está disponible como un perímetro en cualquier objeto de anuncios.

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/v21.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

Añade resultados a un nivel de objeto definido para deduplicar automáticamente los datos.

Solicitud

Por ejemplo, puedes obtener insights de una campaña para un anuncio.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.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 para obtener insights no devolverá ningún dato. Por ejemplo, si solicitas insights con el valor de level establecido en ad, pero no tienes acceso a uno o varios objetos de anuncio desde la cuenta publicitaria, esta llamada a la API devolverá un error de permiso.

Intervalos de atribución

El intervalo de atribución de conversión proporciona intervalos de tiempo que definen cuándo se atribuye un evento a un anuncio en una aplicación de Meta. Para obtener más información, consulta Servicio de ayuda de Meta para empresas, Información sobre los intervalos de atribución. Medimos las acciones que se producen cuando tiene lugar un evento de conversión y retrocedemos 1 día y 7 días. Para ver las acciones atribuidas a distintos intervalos de atribución, realiza una solicitud a /{ad-account-id}/insights. Si no proporcionas action_attribution_windows, utilizamos 7d_click y lo proporcionamos bajo value.

Por ejemplo, especifica action_attribution_windows y el valor se fijará en el intervalo de atribución 7d_click. Realiza una solicitud para act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] y obtendrás 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

Puedes solicitar campos en el nivel de nodo y por campos especificados en la expansión de campos.

Solicitud

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.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"
      }
    }
  }
}

Ordenación

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/v21.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

Estadísticas de todas las etiquetas que tienen un mismo nombre, agrupadas en un único valor a nivel de objeto publicitario. Consulta Etiquetas de anuncios, Referencia 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/v21.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 entender mejor las métricas relacionadas con los clics que se ofrecen actualmente en Meta, consulta a continuación las definiciones y los usos de cada una de ellas:

• Clics en el enlace, actions:link_click: número de clics en enlaces de anuncios a experiencias o destinos específicos dentro o fuera de las propiedades de Meta. Consulta el Servicio de ayuda para publicidad, Clics en el enlace.

• Clics (todos), clicks: estos resultados cuentan varios tipos de clics en el anuncio, incluidos ciertos tipos de interacciones con el contenedor de anuncios, enlaces a otros destinos y enlaces a experiencias publicitarias ampliadas. Consulta Servicio de ayuda para publicidad, Clics (todos)

Objetos archivados y eliminados

Los bloques de anuncios pueden estar en estado DELETED o ARCHIVED. Las estadísticas de los objetos eliminados o archivados aparecen cuando realizas una consulta a sus objetos principales. Esto significa que, si consultas impressions en el nivel del conjunto de anuncios, los resultados incluyen elementos impressions de todos los anuncios del conjunto, independientemente de si tienen el estado eliminado o archivado. Consulta también Prácticas recomendadas para almacenar y recuperar objetos publicitarios.

Sin embargo, si usas la filtración para realizar las consultas, la filtración de estado se aplicará de forma predeterminada para devolver solo los objetos activos. Como consecuencia, las estadísticas totales del nodo principal pueden ser mayores que las de sus objetos secundarios.

Puedes obtener las estadísticas de los objetos ARCHIVED de sus nodos principales. Para hacerlo, proporciona un parámetro filtering adicional.

Solicitud

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

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

Respuesta

Ten en cuenta que en esta respuesta solo se devuelven objetos archivados.

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

Insights de objetos eliminados

Para consultar insights de los objetos eliminados, puedes utilizar su identificador, si lo tienes, o 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/v21.0/AD_SET_ID"
    

En este ejemplo, hacemos la consulta 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

Tiempo de espera agotado

El exceso de solicitudes y el tiempo de espera agotado son los problemas más habituales que provocan un error en este extremo.

• En el caso de solicitudes síncronas o /GET, es posible que recibas errores de memoria o tiempo de espera agotados.
• Con las solicitudes asíncronas o /POST, podrías recibir errores de tiempo de espera agotado. En el caso de las solicitudes asíncronas, se puede tardar hasta una hora en completar una solicitud, incluidos los reintentos (por ejemplo, en caso de realizar una consulta que intente recuperar un gran volumen de datos para muchos objetos de anuncio).

Recomendaciones

• No existe ningún límite explícito respecto al tiempo que tarda en fallar una consulta. Cuando se agote el tiempo de espera, prueba a desglosarla en consultas de menor volumen mediante filtros como el de intervalo de fechas.
• Ten en cuenta que lleva mucho tiempo calcular estadísticas sobre métricas únicas. Prueba a consultar este tipo de datos en una llamada independiente para mejorar el rendimiento de estas métricas.

Limitación de frecuencia

La API de insights de Meta aplica una limitación de frecuencia para garantizar una experiencia óptima en cuanto a la generación de informes para todos nuestros socios. Para obtener más información y sugerencias, consulta los Límites y prácticas recomendadas de la API de insights.

Discrepancia con el Administrador de anuncios

El comportamiento predeterminado de la API es diferente al comportamiento predeterminado en el Administrador de anuncios. Si quieres que el comportamiento sea el mismo que en el Administrador de anuncios, establece en “true” el valor del campo use_account_attribution_setting.

Más información

• Insights de las cuentas publicitarias
• Insights de las campañas publicitarias
• Insights de los conjuntos de anuncios
• Insights de los anuncios

Esta API no cubre extremos que no figuren en la lista anterior. Si tienes previsto incluir informes de Meta en la solución, consulta las Condiciones de la plataforma de Meta y las Políticas para desarrolladores de la API de marketing.