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.

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.

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/v25.0/<AD_ID>/insights"
    

Respuesta

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

Niveles

Combina 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/v25.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 configurado en ad, si no tienes acceso a uno o más objetos de anuncio en la cuenta publicitaria, esta llamada a la API devolverá un error de permiso.

Intervalos de atribución

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 "Información sobre los intervalos de atribución" en el servicio de ayuda de Meta para empresas. 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/v25.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 configurado en {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/v25.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 combinan en un único valor a nivel del 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/v25.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, se aplicará de forma predeterminada un filtrado por estado que hará que se devuelvan solo los 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/v25.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/v25.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 sincrónicas 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 las métricas únicas demanda mucho tiempo. Consulta las métricas únicas en una llamada independiente para mejorar el rendimiento de las métricas que no son únicas.

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, configura el campo use_unified_attribution_setting en true.

Más información

• Estadísticas de la cuenta publicitaria
• Estadísticas de la campaña de anuncios
• Estadísticas del conjunto de anuncios
• Estadísticas de anuncios

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.