Engagement API

​

Descripción general

Enterprise

Esta es una API para empresas disponible únicamente dentro de nuestros niveles de acceso gestionado. Para usar esta API, primero debes configurar una cuenta con nuestro equipo de ventas para empresas. Más información

La Engagement API ofrece acceso a métricas de impresiones e interacción de Publicaciones. Aunque la mayoría de las métricas y endpoints requieren que te autentiques usando OAuth 1.0a User Context, puedes acceder a las métricas públicas de “Favorite”, “Retweet”, “Reply” y “Video Views” usando OAuth 2.0 Bearer Token y el endpoint /totals.  

Nota: Es posible que observes diferencias entre los datos mostrados en algunos de los paneles web de X y los datos informados en la Engagement API. Estas diferencias se producen porque los paneles web normalmente solo muestran interacciones y/o impresiones que ocurrieron dentro del intervalo de tiempo seleccionado. Por ejemplo, un panel web puede mostrar interacción en Publicaciones dentro del período de un mes calendario, mientras que la Engagement API puede mostrar interacciones que quedan fuera de ese mes, pero dentro del intervalo de tiempo solicitado. En estos casos, la Engagement API debe considerarse la fuente de referencia.  

​

Endpoints de solicitud

La Engagement API tiene tres endpoints:

​

Totales actuales: [/totals]

• Las solicitudes devuelven una métrica total de impresiones y una métrica total de interacciones para las Publicaciones especificadas
• Se limita a las siguientes métricas: Impressions, Engagements, Favorites, Replies, Retweets, Quote Tweets y Video Views
• Permite recuperar las métricas de Impressions e Engagements para Publicaciones creadas en los últimos 90 días utilizando OAuth 1.0a User Context
• Permite recuperar las métricas de Favorites, Retweets, Quote Tweets, Replies y Video Views para cualquier Publicación utilizando OAuth 2.0 Bearer Token
• Los resultados se basan en el total actual de impresiones e interacciones en el momento en que se realiza la solicitud
• Ideal para alimentar un panel de informes y para calcular tasas de interacción en una variedad de @handles
• Permite solicitar métricas para hasta 250 Publicaciones por solicitud  

​

Últimas 28 horas: [/28hr]

• Las solicitudes pueden devolver una métrica total de impresiones, una métrica total de interacciones y un desglose de las métricas de interacción individuales que se hayan producido en las últimas 28 horas
• Los datos se pueden agrupar por ID de la Publicación y, en series temporales agregadas, por día o por hora
• Ideal para hacer un seguimiento del rendimiento del contenido creado recientemente
• Compatible con todas las métricas disponibles
• Permite solicitar métricas para hasta 25 Publicaciones por solicitud  

​

Historial: [/historical]

• Las solicitudes pueden devolver impresiones, interacciones y un desglose de métricas de interacción individuales correspondientes al último año, basadas en el momento de la interacción (no en el momento de creación de la Publicación).
• Las solicitudes admiten parámetros de fecha de inicio y fecha de finalización, lo que proporciona flexibilidad para acotar un intervalo de tiempo específico de hasta 4 semanas de duración.
• Los datos de interacción de las Publicaciones se limitan únicamente a los últimos 365 días.
• Los datos se pueden agrupar por ID de la Publicación y, en series temporales agregadas, por día o por hora.
• Ideal para evaluar el rendimiento reciente frente a un punto de referencia histórico o para desarrollar una visión histórica del rendimiento de un @handle.
• Admite todas las métricas disponibles.
• Admite solicitudes de métricas para hasta 25 Publicaciones por solicitud.

​

Métricas disponibles

La siguiente tabla describe los tipos de métricas a las que se puede acceder mediante la API de Engagement.

Consulta nuestra página de interpretación de las métricas para obtener más información sobre las métricas que se muestran a continuación.

Métrica	Disponibilidad del endpoint	Contexto de usuario requerido	Descripción
impressions	Todos	Sí	Número de veces que se ha visto la Publicación. Esta métrica solo está disponible para Publicaciones publicadas en los últimos 90 días.
engagements	Todos	Sí	Número de veces que un usuario ha interactuado con la Publicación. Esta métrica solo está disponible para Publicaciones publicadas en los últimos 90 días.
favorites	Todos	Sí - /28hrs & /Historical No - /totals	Número de veces que se ha marcado la Publicación como favorita.
retweets	Todos	Sí - /28hrs & /Historical No - /totals	Número de veces que se ha retuiteado la Publicación.
quote_tweets	/totals	No - /totals	Número de veces que se ha retuiteado una Publicación con un comentario (también conocido como cita).
replies	Todos	Sí - /28hrs & /Historical No - /totals	Número de veces que se ha respondido a la Publicación.
video_views	Todos	Sí - /28hrs & /Historical No - /totals	Un recuento de cuántas veces un video en la Publicación indicada ha sido visible en un 50 % durante al menos dos segundos. Las visualizaciones de video solo están disponibles para Publicaciones con una antigüedad de 1800 días o menos. Si intentas solicitar visualizaciones de video para cualquier Publicación de más de 1800 días, recibirás el siguiente objeto en tu respuesta, junto con un objeto separado que contiene cualquier otra métrica que hayas solicitado: “unsupported_for_video_views_tweet_ids”: [“TWEET_ID”] Ten en cuenta: Es posible que veas una discrepancia entre la métrica de visualizaciones de video que se muestra en las plataformas propias de X (aplicación móvil y sitio web) y el número que recibes a través de los endpoints /28hr y /historical. * Las visualizaciones de video que se muestran en la interfaz de usuario de X y con el endpoint /totals mostrarán las visualizaciones de video agregadas en todas las Publicaciones en las que se haya incluido el video en cuestión. Esto significa que la métrica mostrada en la interfaz incluye las visualizaciones combinadas de cualquier instancia en la que el video haya sido Retuiteado o republicado en Publicaciones independientes. Esta métrica no incluye visualizaciones de video en GIFs. * Las visualizaciones de video proporcionadas por los endpoints /28hr y /historical solo incluirán aquellas visualizaciones generadas por la Publicación específica para la que solicitas métricas. Esta métrica no incluye visualizaciones de video en GIFs.
media_views	/28hr /historical	Sí	Número total de visualizaciones (reproducción automática y por clic) de tus recursos multimedia, contabilizadas entre videos, GIF e imágenes.
media_engagements (antes Media Clicks)	/28hr /historical	Sí	Número de veces que se ha hecho clic en elementos multimedia, como una imagen o un video, en la Publicación.
url_clicks	/28hr /historical	Sí	Número de veces que se ha hecho clic en una URL de la Publicación.
hashtag_clicks	/28hr /historical	Sí	Número de veces que se ha hecho clic en un hashtag de la Publicación.
detail_expands	/28hr /historical	Sí	Número de veces que se ha hecho clic en la Publicación para ver más detalles.
permalink_clicks	/28hr /historical	Sí	Número de veces que se ha hecho clic en el enlace permanente de la Publicación (la página web individual dedicada a esta Publicación).
app_install_attempts	/28hr /historical	Sí	Número de veces que se ha registrado un evento de instalación de la App originado en la Publicación.
app_opens	/28hr /historical	Sí	Número de veces que se ha registrado un evento de apertura de la App originado en la Publicación.
email_tweet	/28hr /historical	Sí	Número de veces que se ha compartido la Publicación por correo electrónico.
user_follows	/28hr /historical	Sí	Número de veces que se ha seguido al usuario (autor de la Publicación) desde esta Publicación.
user_profile_clicks	/28hr /historical	Sí	Número de veces que se ha hecho clic en el perfil del usuario (autor de la Publicación) desde esta Publicación.

​

Agrupaciones de interacción

Las agrupaciones permiten organizar de forma personalizada las métricas de interacción que se devuelven. Puedes incluir hasta 3 agrupaciones por solicitud. Puedes elegir agrupar las métricas por uno o más de los siguientes valores:

Los tres endpoints admiten:

• tweet.id
• engagement.type  

Los endpoints /28hr y /historical pueden proporcionar métricas de series temporales y, por lo tanto, admiten:

• engagement.day
• engagement.hour

Para obtener más información sobre las agrupaciones, visita la página Engagement API Grouping en la sección Guías.

​

Guías

​

Guía de primeros pasos para desarrolladores

​

Introducción

El propósito de esta documentación es ofrecer a los desarrolladores una introducción a cómo integrar la Engagement API. Comenzaremos analizando los motivos para integrarse y luego profundizaremos en los detalles técnicos del “cómo”.

¿Qué ofrece la Engagement API?

• La Engagement API proporciona datos de impresiones e interacción para todas las Publicaciones propias de cualquier cuenta de X de los últimos 90 días, siempre que esa cuenta haya autorizado a tu App a solicitar métricas en su nombre usando 3-legged OAuth. Esta solución potente pero fácil de implementar ofrece acceso inmediato a impresiones e interacciones profundas, como clics en URL, clics en hashtags y muchas más.
• La Engagement API proporciona métricas agregadas totales de Me gusta, Retweets, Quote Tweets, respuestas y visualizaciones de vídeo para cualquier Publicación. Esto se puede usar como una forma eficaz de obtener datos básicos de interacción sobre cualquier Publicación o colección de Publicaciones.
• La Engagement API aporta nuevo valor a las plataformas de escucha social, marketing y publicación al permitir que los clientes midan el ROI en X midiendo de forma eficaz el rendimiento del contenido mediante más de 15 métricas de rendimiento.
• La Engagement API es una API de solicitud/respuesta que permite a los desarrolladores de aplicaciones enviar solicitudes con ids de Publicaciones, las métricas deseadas y un intervalo de tiempo, para lo cual la API devuelve los datos al instante.  

¿Por qué integrar? Casos de uso de ejemplo

• Comprender el alcance total de mi contenido para ver cuántas personas lo ven. Ver cuántas personas ven videos, hacen clic en enlaces, hacen clic en hashtags o instalan mis apps.
• Generar métricas de interacción tanto totales como de series temporales.
• Comprender métricas de interacción básicas (favoritos, Retweets, Tweets citados, respuestas) sobre cualquier Publicación pública.
• Usar estas métricas para determinar qué tipos de Publicaciones funcionan para poder publicarlas con más frecuencia y obtener más impresiones y más interacciones para mi contenido.
• Automatizar el comportamiento de marketing (como hacer Retweet del contenido de otra cuenta de mi propiedad) cada vez que una de mis Publicaciones alcance 100 Likes u otro umbral.
• Comparar mis campañas entre sí y utilizarlas como herramienta para realizar pruebas A/B.
• Analizar qué tipo de contenido genera mayor respuesta para mi departamento de atención al cliente a fin de determinar cómo y cuándo responder.
• Mostrar métricas de analítica para el contenido que se publica desde mi plataforma.  

La Engagement API se lanzó en 2016 y fue la primera X API en proporcionar estas métricas de interacción detalladas a escala. La Engagement API es fácil de usar y permite a los clientes automatizar el proceso. Aquí se presenta un estudio de caso que describe una integración de ejemplo:

• Measuring campaign success with the Red Cross

Ahora que hemos explorado los “porqués” de la Engagement API, empecemos a profundizar en los detalles técnicos.

​

Integración de la API de Engagement

Introducción a la API

La Engagement API es una API RESTful sencilla que recibe solicitudes codificadas en JSON y responde con métricas de interacción codificadas en JSON. Las solicitudes constan de tres partes principales (consulta los enlaces para más documentación):

• Array de IDs de Publicación.
• Array que especifica los tipos de métricas de interés. Los tipos incluyen cosas como ‘impressions’, ‘retweets’, ‘hashtag_clicks’ y ‘user_follows’.
• Agrupaciones de interacción, que es una estructura JSON que indica cómo deseas que se organicen los datos de interacción en la respuesta de la API.

En muchas situaciones, los tipos de interacción y las agrupaciones se mantendrán relativamente constantes de una solicitud a otra, actualizándose únicamente los IDs de Publicación.

La Engagement API proporciona tres endpoints:

• Totals - Proporciona totales generales de interacciones para Publicaciones. Algunas métricas están disponibles para todas las Publicaciones, mientras que otras solo están disponibles para los últimos 90 días.
• 28 hour - Proporciona métricas de interacción en series temporales de las últimas 28 horas.
• Historical - Proporciona métricas de interacción en series temporales de hasta cuatro semanas consecutivas para Publicaciones publicadas desde el 1 de septiembre de 2014.

El endpoint /totals permite solicitar métricas para hasta 250 Publicaciones por solicitud. Los endpoints /28hour y /historical permiten 25 por solicitud.

Después de explicar cómo obtener acceso a la Engagement API, recorreremos el proceso de hacer una solicitud a la API, ofreceremos una descripción general de OAuth y proporcionaremos enlaces a otros recursos técnicos.

Obtener acceso a la API

Si está leyendo este documento, lo más probable es que ya tenga acceso a la Engagement API. Si no es así, póngase en contacto con su administrador de cuenta de Enterprise o solicite acceso de Enterprise aquí.

El primer paso es crear una App de X usando una cuenta de desarrollador aprobada a través de la Consola de desarrollador. Su administrador de cuenta necesitará el ID numérico de la App asociado con esta aplicación para poder otorgar acceso. Si necesita solicitar una cuenta de desarrollador, puede hacerlo aquí.

Realizar una solicitud

La buena noticia es que realizar solicitudes a la Engagement API es sencillo. Para nuestra solicitud, le pediremos el total de Retweets, Tweets citados, Favoritos y respuestas para las siguientes dos Publicaciones de @XDevelopers:

1/ Hoy compartimos nuestra visión para el futuro de la plataforma X API.https://t.co/XweGngmxlP

— Twitter Dev (@TwitterDev) 6 de abril de 2017

No te pierdas las Publicaciones sobre tu Publicación.

Ahora en iOS puedes ver los Retweets con comentarios en un solo lugar. pic.x.com/oanjZfzC6y

— X (@X) 12 de mayo de 2020

El primer paso es construir la solicitud a la API en JSON, que consiste en estos dos id de Publicaciones colocados en un array, un array de tipos de interacción de interés y un objeto JSON con nombre personalizado “groupings” que indica cómo queremos que se organicen las métricas en la respuesta. Así es como se ve nuestra solicitud:

{
  "tweet_ids": [
    1260294888811347969, 850006245121695744
  ],
  "engagement_types": [
    "retweets", "quote_tweets", "favorites", "replies"
  ],
  "groupings": {
    "engagement-types-by-id": {
      "group_by": [
        "Tweet.id", "engagement.type"
      ]
    }
  }
}

Para recuperar estas métricas totales, realizamos una solicitud POST con este JSON al endpoint https://data-api.x.com/insights/engagement/totals.

Incluiremos los siguientes encabezados para indicar que nuestra solicitud está codificada en JSON y que está comprimida con Gzip (los cuerpos de las solicitudes pueden ser grandes):

• Content-Type: application/json
• Accept-Encoding: gzip  

Al hacer solicitudes, nos autenticamos con OAuth, de lo cual hablaremos con más detalle en la siguiente sección.

La API devuelve la siguiente carga útil:

{
  "grouping name": {
    "1260294888811347969": {
      "favorites": "17111",
      "quote_tweets": "3254",
      "replies": "1828",
      "retweets": "5218"
    },
    "850006245121695744": {
      "favorites": "492",
      "quote_tweets": "66",
      "replies": "42",
      "retweets": "324"
    }
  }
}

Ten en cuenta que la respuesta contiene las métricas que solicitamos en la estructura descrita por las definiciones de “groupings”, con las métricas organizadas primero por ID de la Publicación y luego por tipo de interacción en el siguiente nivel.

Eso fue bastante sencillo. Si eres nuevo en la autenticación con OAuth, consulta la siguiente sección.

​

Autenticación con OAuth

OAuth es un estándar de autenticación muy común en la industria tecnológica. Si ya estás usando OAuth (quizás con otras X API), es probable que estés utilizando un paquete de OAuth específico para tu lenguaje de programación que abstrae todos los detalles complicados. Si eres nuevo en OAuth, visita nuestra página OAuth con la X API o dirígete directamente a https://oauth.net para obtener más información. Luego te recomendamos que busques un paquete OAuth para el lenguaje de integración de tu preferencia y comiences por ahí. Con estos paquetes, el proceso de autenticación normalmente consiste en configurar tus claves y tokens, crear algún tipo de objeto HTTP y, después, realizar solicitudes con ese objeto.

Por ejemplo, en el mundo de Ruby, el siguiente seudocódigo representa una receta para crear una App con OAuth habilitado usando la gema de Ruby ‘oauth’ y realizando una solicitud POST:

require 'oauth'

#Ensamblar la solicitud JSON (como se indicó arriba).
request = make_json_request()

#Crear un objeto consumidor de la aplicación con la consumer key y el consumer secret de mi aplicación.
consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => ‘https://data-api.x.com’})
#Crear un token de usuario con los tokens proporcionados por la cuenta que otorga el permiso. Si se realiza una solicitud solo de aplicación (consultando Tweets que no requieren permiso con el endpoint /totals), se puede omitir este paso.
token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']}

#Crear un objeto de aplicación habilitado para OAuth.
app = OAuth::AccessToken.from_hash(consumer, token)
#Realizar una solicitud POST.
result = app.post(“/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"})

La Engagement API admite autenticación solo de aplicación y con contexto de usuario. Si estás recopilando métricas de interacción para Publicaciones públicas que no te pertenecen con el endpoint /totals, entonces no se requiere permiso de usuario y puedes usar autenticación solo de aplicación. En este caso, usarás únicamente la clave y el secreto de tu App para autenticarte.

OAuth también permite que una App realice una solicitud a la API “en nombre de otro usuario”, utilizando tokens asociados al usuario. Si estás generando métricas de interacción para Publicaciones propias, es decir, Publicaciones que fueron publicadas por un usuario para el que tienes tokens de usuario, estarás realizando solicitudes con un contexto de usuario, lo que significa autenticarte tanto con las claves de tu App como con tokens de acceso específicos del usuario. Estos tokens de acceso de usuario normalmente se proporcionan con el proceso ‘Sign-in with X’ o se obtienen directamente del usuario (ten en cuenta que debes usar twurl si obtienes los tokens directamente del usuario). Una vez que el usuario proporciona sus tokens, estos no caducan y pueden utilizarse con la Engagement API para realizar solicitudes en su nombre, siempre y cuando el usuario no restablezca sus tokens ni cambie su contraseña; en ese caso, tendrá que proporcionarte los nuevos tokens.

Puedes consultar qué métricas requieren qué tipo de autenticación en esta tabla.

​

Seleccionar un endpoint de la Engagement API

La Engagement API ofrece tres endpoints distintos:

• Totals - proporciona totales globales de métricas seleccionadas de Publicaciones ‘owned’ o ‘unowned’. Algunas métricas están disponibles para todas las Publicaciones, mientras que otras solo están disponibles para Publicaciones publicadas en los últimos 90 días. Admite 250 Publicaciones por solicitud.
• 28 hour - proporciona métricas de Engagement en series temporales para Publicaciones ‘owned’ de las últimas 28 horas. Admite 25 Publicaciones por solicitud.
• Historical - proporciona métricas de Engagement en series temporales para hasta cuatro semanas consecutivas para Publicaciones ‘owned’ publicadas desde el 1 de septiembre de 2014. Admite 25 Publicaciones por solicitud.  

Cada endpoint tiene sus propias características específicas. Ya sea que tengas previsto usar los tres, o que solo estés intentando decidir cuál se ajusta mejor a tu caso de uso, es importante entender las diferencias entre ellos.

A continuación presentamos algunos conceptos clave, exploramos con más detalle los tres endpoints y luego mostramos casos de uso de ejemplo que se corresponden de forma general con un endpoint específico. Nuestra intención es que esta información te ayude a integrar los tres de forma más eficiente o a decidir qué endpoint en particular encaja mejor con tu objetivo.  

​

Conceptos clave

Existen varios conceptos clave que ayudan a ilustrar las distintas características y los datos que proporcionan los tres endpoints de la Engagement API.  

Impresiones y métricas de engagement

Las impresiones representan la cantidad de veces que una determinada Publicación se ha visto en la plataforma X en un contexto orgánico. No se incluyen las impresiones generadas por Publicaciones que se ven en un contexto Promocionado o de pago. Antes de la Engagement API, las impresiones de una Publicación representaban únicamente una medida de visualizaciones potenciales. Se basaban en contar los seguidores de la cuenta del autor y los de cualquier cuenta que hiciera Retweet del contenido. No se tenía en cuenta la situación común en la que un usuario determinado en realidad no ve la Publicación.

Las métricas de impresiones generadas por la Engagement API constituyen una medida real de la cantidad de veces que una Publicación se ha renderizado para mostrarse en pantalla. Si un seguidor de tu cuenta no ve tu Publicación, no cuenta como una impresión.

La Engagement API proporciona 14 tipos únicos de métricas de engagement (metric types), cada una de las cuales representa una acción distinta que un usuario puede realizar cuando se muestra una Publicación. Estas incluyen hacer Retweet, indicar “Me gusta”, responder, hacer clic en entidades como #hashtags, enlaces y contenido multimedia, seguir al autor y ver el perfil del autor. Todas estas acciones individuales se consolidan en una única métrica denominada Engagements.

Contenido de X propio y no propio

La Engagement API establece una clara distinción entre Publicaciones propias y no propias. Las Publicaciones propias son Publicaciones publicadas desde tu cuenta o Publicaciones para las que has obtenido permiso para solicitar datos de Engagement. Como en otras APIs de X, obtienes permiso cuando otros usuarios o cuentas de X comparten tokens de acceso que te permiten realizar solicitudes a la API en su nombre. Una forma común de obtener estos tokens es mediante el proceso «Inicia sesión con X».

El endpoint /totals proporciona datos de engagement tanto para Publicaciones propias como no propias. Para las Publicaciones no propias, puedes solicitar las métricas de engagement que están disponibles públicamente en la vista de una Publicación: Favorite, Retweet y Reply. Para estas métricas, lo que aporta la Engagement API es la capacidad de recuperarlas a escala y de forma automatizada. Para las Publicaciones propias, el endpoint /totals también proporciona las métricas de Impression y Engagement (total).

Los endpoints /28hr e /historical proporcionan métricas solo para Publicaciones propias, lo que significa que debes incluir el contexto de usuario cuando hagas la solicitud a estos endpoints.

Datos de engagement totales y de series temporales

El endpoint /totals proporciona, como su nombre indica, solo totales globales para sus tipos de engagement. Sus cifras representan los totales actualizados desde que se publicó la Publicación. Si acabas de publicar una Publicación y solicitas sus métricas de forma repetida, estos totales normalmente cambiarán con cada solicitud.

Los endpoints /28hr y /historical pueden proporcionar tanto totales globales como datos de series temporales. Al solicitar datos de series temporales, las métricas de engagement se pueden consolidar en datos diarios o por hora.   

Consulta nuestra documentación sobre agrupaciones de engagement para obtener información sobre cómo solicitar datos de series temporales con los endpoints /28hr y /historical.

​

Endpoints y ejemplos de casos de uso

Dadas las características y diferencias mencionadas anteriormente, cada endpoint individual generalmente se corresponde con distintos tipos de casos de uso. Para ayudarte a decidir qué endpoint se adapta mejor a tu caso de uso en particular, a continuación se muestran algunos ejemplos de planteamientos de usuarios y el endpoint que mejor los satisface.

/totals

• Solo necesito acceso a algunos tipos de métricas (Impressions, Engagements, Favorites, Retweets, Quote Tweets, Replies y Video Views).
• Necesito acceso a datos básicos de interacción para cualquier Publicación, no solo para Publicaciones propias.
• Quiero comparar el rendimiento con un competidor.
• Quiero hacer un seguimiento de estadísticas básicas de interacción para un hashtag o campaña que incluya Publicaciones que no son mías.
• No necesito datos desglosados por día u hora, solo necesito el total actual cuando hago una solicitud.
• Necesito una sola métrica para mostrar en un informe o panel de control y no quiero almacenar ningún dato.
• Quiero mostrar datos al cargar la página y solo necesito hacer una solicitud y recibir una respuesta.
• Necesito poder obtener datos de cientos de miles o millones de Publicaciones por día.  

/28hr

• Necesito acceso a los 17 tipos de métricas.
• Quiero mostrar datos de Publicaciones muy recientes de las últimas 28 horas.
• Tengo un proceso que se ejecuta una vez al día para obtener los datos que me interesan y solo necesito obtener datos del último día.
• Necesito que las métricas estén desglosadas por día u hora.
• Quiero mostrar desgloses de series temporales de la actividad por hora en un panel de control.
• Necesito un nivel de acceso alto para cientos de miles de Publicaciones por día.
• Tengo capacidad de almacenamiento y puedo actualizar los datos una vez al día y mantener un recuento acumulado.  

/historical

• Necesito acceso a los 17 tipos de métricas.
• Necesito obtener datos históricos de Publicaciones creadas retroactivamente hasta septiembre de 2014.
• Quiero mostrar un análisis histórico detallado que compare campañas.
• Necesito que las métricas estén desglosadas por día o por hora.
• No necesito altos niveles de acceso a la Engagement API y solo necesito obtener datos para unos cientos o miles de Publicaciones por día.

​

Características clave de la Engagement API

• API RESTful que proporciona datos JSON y admite solicitudes POST con cuerpos de datos JSON.
• Tipos de solicitudes: Las aplicaciones cliente pueden realizar los siguientes tipos de solicitudes:
  • Engagements totales — Solicitud HTTP POST al endpoint /totals
  • Engagements de las últimas 28 horas — Solicitud HTTP POST al endpoint /28hr
  • Engagements históricos — Solicitud HTTP POST al endpoint /historical
• Autenticación OAuth:
  • OAuth 1.0 User Context: Todas las métricas disponibles están disponibles para Publicaciones que son propiedad de un usuario que haya autorizado tu App usando 3-legged OAuth. Debes usar los Access Tokens de ese usuario cuando hagas tu solicitud.
  • OAuth 2.0 Bearer Token: Métricas seleccionadas (Retweets, Quote Tweets, Replies, Favorites y Video Views) están disponibles para cualquier Publicación pública. 
• Metadatos y estructura de la solicitud: Los datos de la solicitud son un objeto JSON compuesto por un array de Post IDs, un array de tipos de engagement y una estructura de agrupación de engagement.
• Publicaciones por solicitud:
  • Endpoint /totals: 250 Post IDs
  • Endpoint /28hr: 25 Post IDs
  • Endpoint /historical: 25 Post IDs
• Disponibilidad de métricas de engagement:
  • /totals — Totales de métricas desde el momento en que se publicó la Publicación. Impressions y Engagements están disponibles para Publicaciones publicadas en los últimos 90 días, mientras que Retweets, Quote Tweets, Replies, Favorites y Video Views están disponibles para todas las Publicaciones.
  • /28hr — Últimas 28 horas desde el momento de la solicitud.
  • /historical — Cualquier período de 28 días a partir del 1 de septiembre de 2014.
• Tipos de métricas: Cada solicitud incluye un array de Metric Types. La disponibilidad de estos depende del endpoint y, si se solicita desde el endpoint /totals, de si las Publicaciones tienen permisos de usuario.
  • Endpoint /totals:
    • Todas las Publicaciones: Favorites, Retweets, Quote Tweets, Replies y Video Views
    • Requiere OAuth 1.0a User Context: Impressions, Engagements, Favorites, Replies y Retweets
  • Endpoints /28hr y /historical (requiere OAuth 1.0a User Context con el Access Token del propietario de la Publicación): Impressions, Engagements, Favorites, Replies, Retweets, URL Clicks, Hashtag Clicks, Detail Click, Permalink Clicks, Media Clicks, App Install Attempts, App Opens, Post Emails, Video Views y Media Views
• Agrupaciones de engagement: Cada solicitud incluye un array de Engagement Groupings. Con estas agrupaciones puedes personalizar cómo se organizan las métricas devueltas. Se pueden incluir hasta tres agrupaciones en cada solicitud. Las métricas se pueden organizar según los siguientes valores:
  • Todos los endpoints: Post ID, Engagement Type
  • Endpoints /28hr y /historical: Estos endpoints proporcionan series temporales si se especifican estas agrupaciones adicionales: Engagement Day, Engagement Hour
• Expectativas de integración: Tu equipo será responsable de lo siguiente.
  • Crear y mantener una aplicación cliente que pueda enviar solicitudes HTTP a la Engagement API para obtener métricas de engagement para el Post ID incluido en la solicitud.
• Limitaciones
• Video Views solo están disponibles para Publicaciones con una antigüedad de 1800 días o menos.

​

Autenticación con la Engagement API

Ten en cuenta: 

X debe habilitar el acceso a la Engagement API para tu App de desarrollador antes de que puedas empezar a usar la API. Para ello, asegúrate de compartir el App ID que piensas usar para fines de autenticación con tu gestor de cuenta o equipo de soporte técnico.

Hay dos métodos de autenticación disponibles con la Engagement API: OAuth 1.0a y OAuth 2.0 Bearer Token. 

OAuth 2.0 Bearer Token (también conocido como “application-only”) te permite acceder a métricas de interacción disponibles públicamente. Este método de autenticación se puede usar para obtener los recuentos totales de Favorites (también llamados Likes), Retweets, Quote Tweets, Replies y visualizaciones de vídeo para cualquier Publicación disponible públicamente al hacer solicitudes al /totals endpoint. 

OAuth 1.0a (también conocido como “user context”) te permite hacer solicitudes en nombre de un usuario y acceder a métricas de interacción privadas que pertenecen al usuario en cuestión. 

Este método de autenticación es obligatorio para:

• Todas las solicitudes enviadas al /28hr endpoint y al /historical endpoint
• Acceder a cualquiera de las siguientes métricas privadas: Impressions, Engagements, Media Views, Media Engagements, URL Clicks, Hashtag Clicks, Detail Expands, Permalink Clicks, App Install Attempts, App Opens, Email Post, User Follows y User Profile Clicks

Al enviar una solicitud con OAuth 1.0a, debes incluir los tokens de acceso (Access Token y Secret) del usuario que es propietario de la Publicación o del recurso protegido de interés. Si no proporcionas los tokens de acceso correctos del usuario al solicitar datos de usuario protegidos, la Engagement API devolverá un error 403 Forbidden.

La Engagement API no te permitirá obtener datos de interacción de Publicaciones protegidas, incluso si te estás autenticando en nombre del usuario propietario de estas Publicaciones. Si lo intentas, se devolverá un error 400 Bad Request, con el mensaje "Tweet ID(s) are unavailable".

Si estás enviando una solicitud en nombre de tu propia cuenta de X (es decir, la cuenta que es propietaria de la App de desarrollador), puedes generar los tokens de acceso necesarios directamente desde la Consola de desarrollador, en la pestaña “Keys and tokens” de la App de desarrollador.

Si estás realizando una solicitud en nombre de cualquier otro usuario, tendrás que usar el flujo OAuth con 3 pasos (3-legged OAuth) para obtener los tokens de acceso necesarios. La siguiente documentación contiene más información sobre cómo hacerlo: OAuth 1.0a: how to obtain a user’s access tokens.

Para ejemplos adicionales, incluido cómo autenticarse usando OAuth 1.0a, consulta el código de ejemplo en Python de X Developers para la Engagement API.

​

Cambios recientes en la Engagement API

La Engagement API ofrece métricas de impresiones e interacción sumamente valiosas que te permiten supervisar el rendimiento de tu actividad en X. En nuestro esfuerzo continuo por facilitar decisiones de marketing basadas en nuestros datos, nos complace compartir cambios recientes en la Engagement API que proporcionan una mayor coherencia de las métricas en todo X.  

Recientemente implementamos cambios para modernizar la Engagement API y utilizar la misma metodología de agregación de métricas que se usa en el panel de analíticas de X (analytics.x.com). Adoptamos un enfoque cuidadoso para intentar minimizar los cambios disruptivos en la API al lanzar estas nuevas métricas y desplegamos el primer conjunto de cambios el 9 de octubre de 2017. Estos cambios mejoran la coherencia entre todos los lugares en los que tú o tus clientes podáis supervisar vuestro rendimiento en X. Consulta a continuación el resumen detallado de los cambios:

Metric	Change
engagements	Hemos actualizado las métricas que se agregan en el total de engagements para que coincidan con el panel de analíticas de Publicaciones. Engagements mide “las veces que las personas interactuaron con esta Publicación”. Para las Publicaciones que incluyen contenido multimedia como un video o un GIF, la métrica engagements ya no incluirá media views. Ahora puedes acceder a las visualizaciones de contenido multimedia mediante una nueva métrica, media_views.
media_clicks*	Esta métrica ha sido reemplazada por una nueva métrica llamada “media_engagements”.
video_views	Desde el 6 de julio de 2018, esta métrica está disponible para Publicaciones “no propias” a través del endpoint /totals. Esto significa que puedes acceder a las visualizaciones de video de todas las Publicaciones usando autenticación solo de App.  Solo puedes solicitar visualizaciones de video de hasta 1800 días de antigüedad. Si intentas solicitar visualizaciones de video para una Publicación con más de 1800 días, recibirás lo siguiente: “unsupported_for_video_views_tweet_ids”: [“TWEET_ID”] Ten en cuenta que diferirá de media_views en que video_views se basa en el estándar MRC del 50% del video visible durante al menos dos segundos. Además, ten en cuenta que puedes observar una discrepancia entre la métrica de visualizaciones de video mostrada en las plataformas de X de titularidad y operación propia (aplicación móvil y sitio web) y el número que recibes a través de los endpoints /28hr y /historical. * Las visualizaciones de video que se muestran en la interfaz de usuario de X y que se entregan usando el endpoint /totals mostrarán la métrica de visualizaciones de video agregada entre todas las Publicaciones en las que se haya publicado ese video. Esto significa que la métrica mostrada en la IU incluye las visualizaciones combinadas de cualquier instancia en la que el video haya sido Retwitteado o vuelto a publicar en Publicaciones independientes. * Las visualizaciones de video proporcionadas por los endpoints /28hr y /historical solo incluirán aquellas visualizaciones generadas por la Publicación específica para la que estás obteniendo métricas.
media_views	Esto incluye todas las visualizaciones (reproducción automática y por clic) de tu contenido multimedia contabilizadas en videos, vines, gifs e imágenes. Ten en cuenta que las Publicaciones con imágenes no muestran una métrica media_views en el panel de analíticas, pero sí se devolverá en la Engagement API.
media_engagements*	Esto incluye el número de clics en tu contenido multimedia en videos, vines, gifs e imágenes. Esta métrica sustituye a media_clicks.
quote_tweets	Desde el 7 de julio de 2020, esta métrica está disponible para Publicaciones “no propias” a través del endpoint /totals. Esto significa que puedes acceder al recuento de Publicaciones con cita para todas las Publicaciones utilizando autenticación solo de App.

​

Interpretación de las métricas

Nota: Es posible que observe diferencias entre los datos mostrados en algunos de los paneles web de X y los datos devueltos por la Engagement API. Estas diferencias se producen porque los paneles web suelen mostrar solo las interacciones y/o impresiones que ocurrieron dentro del período de tiempo seleccionado. Por ejemplo, un panel web puede mostrar la interacción con Publicaciones durante un mes calendario, mientras que la Engagement API puede mostrar interacciones que se extienden más allá de ese mes, pero que siguen estando dentro del período de tiempo solicitado. En estos casos, la Engagement API debe considerarse la fuente válida.  

​

Datos de impresiones e interacción

La Engagement API proporciona datos de impresiones orgánicas e interacción.

Las impresiones representan el número de veces que una determinada Publicación se ha visto en la plataforma X en un contexto orgánico. Las impresiones generadas a partir de Publicaciones que se ven en un contexto promocionado o de pago no se incluyen.

Las interacciones representan el número de veces que una determinada Publicación recibió una interacción por parte de un espectador, tanto en un contexto orgánico como promocionado. Las interacciones incluyen, entre otras, Retweets, Favorites, Replies, URL Clicks, Hashtag Clicks, Mention Clicks y Media Views. Para ver la lista completa de acciones de interacción incluidas, consulta la sección Engagement Data. 

Para calcular una tasa de interacción de referencia, utiliza el número total de interacciones dividido por el número total de impresiones de una determinada Publicación para el período de tiempo que estés analizando.

Los datos de impresiones e interacción solo se pueden recuperar para Publicaciones de @handles propios o de @handles que hayan autorizado tu aplicación a ver los detalles de sus Publicaciones. Internamente, la Engagement API realizará un seguimiento del número de @handles únicos que se hayan solicitado en relación con el límite de @handles contratado. Se recomienda también hacer un seguimiento del uso de solicitudes de @handle del lado del cliente a lo largo del mes.  

​

Métricas de vídeo

Hay un par de métricas diferentes que representan impresiones de contenido multimedia dentro de X. La primera es nuestra métrica de visualizaciones de vídeo, que se basa en el estándar MRC de que al menos el 50% del vídeo esté visible durante al menos dos segundos. La segunda es Media Views, que incluye todas las visualizaciones (reproducción automática y por clic) de tu contenido multimedia contabilizadas en vídeos, vines, GIF e imágenes.

La métrica de visualizaciones de vídeo está disponible para Publicaciones propias a través de los endpoints /28hour y /historical, así como para todas las Publicaciones ajenas a través del endpoint /totals. 

Aunque la métrica de visualizaciones de vídeo dentro de la interfaz de usuario de X utiliza el mismo estándar MRC, ten en cuenta que puedes observar una discrepancia entre la métrica de visualizaciones de vídeo que se muestra en las plataformas propiedad de X y operadas por esta (aplicación móvil y sitio web) y el número que recibes a través de los diferentes endpoints de Engagement API.

• Las visualizaciones de vídeo proporcionadas por el endpoint /totals y la interfaz de usuario de X mostrarán las visualizaciones de vídeo agregadas en todas las Publicaciones en las que se haya publicado ese vídeo. Esto significa que la métrica entregada mediante /totals y mostrada en la interfaz de usuario de X incluye las visualizaciones combinadas de cualquier instancia en la que el vídeo haya sido Retweeted o republicado en Publicaciones separadas.
• Las visualizaciones de vídeo proporcionadas por los endpoints /28hour y /historical de Engagement API solo incluirán aquellas visualizaciones generadas por la Publicación específica para la cual estás obteniendo métricas.   

Ten en cuenta que no proporcionamos visualizaciones de vídeo para Publicaciones que tengan más de 1800 días de antigüedad. En su lugar, proporcionamos un objeto que enumera las Publicaciones que son más antiguas que 1800 días. Aun así, recibirás todas las demás métricas para las Publicaciones solicitadas en un objeto separado. Aquí tienes un ejemplo de respuesta:

{
  "unsupported_for_video_views_tweet_ids": [
    "479311209565413376",
    "477139122520219648"
  ],
  "grouping name": {
    "479311209565413376": {
      "favorites": "69",
      "impressions": "1692",
      "retweets": "142",
      "video_views": "0"
    },
    "477139122520219648": {
      "favorites": "10",
      "impressions": "1023",
      "retweets": "6",
      "video_views": "0"
    },
    "1397568983931392004": {
      "favorites": "268",
      "impressions": "26803",
      "retweets": "56",
      "video_views": "17902"
    }
  }
}

La métrica Media Views solo está disponible para Publicaciones propias en los endpoints /28hour y /historical.

​

Agrupaciones de la Engagement API

Las agrupaciones permiten una organización personalizada de las métricas de engagement devueltas. Puedes incluir un máximo de 3 agrupaciones por solicitud. Puedes elegir agrupar las métricas por uno o más de los siguientes valores:

Los tres endpoints admiten:

• tweet.id
• engagement.type  

Los endpoints /28hr y /historical pueden proporcionar métricas de series temporales y, por lo tanto, admiten:

• engagement.day
• engagement.hour

Las agrupaciones se aplican de forma secuencial, de modo que puedes cambiar el formato de resultado deseado modificando el orden de tus valores group_by. Las agrupaciones que contienen cuatro valores group_by solo serán compatibles en uno de los dos formatos siguientes:

"group_by": [
    "tweet.id",
    "engagement.type",
    "engagement.day",
    "engagement.hour"
  ]

O

"group_by": [
    "engagement.type",
    "tweet.id",
    "engagement.day",
    "engagement.hour"
]

Por ejemplo, si quieres generar totales globales de tipos de métricas, incluye la siguiente especificación de “groupings” como parte de tu solicitud (y consulta la página de Referencia de la API para obtener más información sobre cómo crear las solicitudes):

{
  "engagement_types": [
    "favorites",
    "replies",
    "retweets"
  ],
  "groupings": {
    "Grand Totals": {
      "group_by": [
        "engagement.type"
      ]
    }
  }
}

Con esta agrupación, la respuesta JSON de la Engagement API incluirá un atributo de nivel raíz "Grand Totals" que contiene los totales generales por type de métricas:

{
  "Grand Totals": {
    "favorites": "12",
    "replies": "2",
    "retweets": "2"
  }
}

Para generar una serie temporal de métricas con intervalos de 4 horas para una sola Publicación, agrupada por ids de Publicación, la siguiente especificación de Grouping sería parte de la solicitud:

{
  "start": "2016-02-10T17:00:00Z",
  "end": "2016-02-10T21:00:00Z",
  "tweet_ids": [
    "697506383516729344"
  ],
  "engagement_types": [
    "impressions",
    "engagements"
  ],
  "groupings": {
    "Tweets_MetricType_TimeSeries": {
      "group_by": [
        "tweet.id",
        "engagement.type",
        "engagement.hour"
      ]
    }
  }
}

Con esta agrupación, la respuesta JSON de Engagement API incluirá un atributo en el nivel raíz "Tweets_MetricType_TimeSeries" que contiene las métricas desglosadas por id de Publicación, luego por tipo de métrica y la correspondiente serie temporal por horas:

{
  "Tweets_MetricType_TimeSeries": {
    "697506383516729344": {
      "impressions": {
        "2016-02-10": {
          "17": "551",
          "18": "412",
          "19": "371",
          "20": "280"
        }
      },
      "engagements": {
        "2016-02-10": {
          "17": "8",
          "18": "6",
          "19": "3",
          "20": "0"
        }
      }
    }
  }
}

​

Preguntas frecuentes

Enterprise

​

Engagement API

¿Cómo puedo acceder a la Engagement API?

El acceso a la Engagement API se habilita a través de una suscripción empresarial. Completa este formulario para ponerte en contacto con nuestro equipo de ventas.

¿Cómo se realiza el seguimiento de mi uso por '@handle'?

Si tu contrato incluye un límite para la cantidad de handles únicos que se pueden usar con Engagement API, el sistema interno de X llevará un seguimiento del número de usuarios autenticados propietarios de Publicaciones que se consultan con la Engagement API. Los clientes también deberían hacer un seguimiento de este número único en el lado del cliente. Actualmente, no existe ninguna API de uso ni interfaz de usuario para comprobar el uso de @handle en la Engagement API. El sistema no bloqueará los excesos de uso si se solicitan más @handles de los que se han contratado. Al final del mes de facturación, el número de @handles únicos consultados se compara con la cantidad contratada y se aplicará un cargo por exceso de uso de acuerdo con los términos del contrato.

¿Puedo comprobar mi uso de @handle para la Engagement API?

Actualmente, no existe ninguna API de uso ni interfaz de usuario para comprobar el uso de @handle en la Engagement API. El sistema no bloqueará los excesos de uso si se solicitan más @handles de los que se han contratado. Al final del mes de facturación, el número de @handles únicos consultados se compara con la cantidad contratada y se aplicará un cargo por exceso de uso de acuerdo con los términos del contrato.

El campo de metadatos engagements devuelto en el payload no es igual a la suma de todos los totales de las distintas métricas de interacción. ¿Por qué ocurre esto?

Esto es lo esperado. El campo de metadatos engagements puede no coincidir siempre con la suma de todas las métricas de interacción individuales devueltas por la API. Esto se debe a que el campo de metadatos engagements puede incluir interacciones adicionales que no tienen métricas específicas desglosadas en el payload. Dicho de otra manera, sumar todos los totales de las distintas métricas de interacción puede no ser igual al valor que ves en el campo de métrica engagements que se devuelve en el payload.

Puedes considerar el campo de metadatos engagements como cualquier clic o interacción realizada en la Publicación.  

El campo url_clicks en la respuesta del payload devuelve un número, cuando en realidad la Publicación no tiene una URL. ¿Cómo es posible?

Esto puede deberse a que una Publicación que contiene algo como un hashtag (que crea un enlace a otra página) contará como un clic de URL si un usuario hace clic en él.  

¿Por qué no puedo recibir datos de interacción para una Publicación específica?

Hay varios motivos por los que podrías no poder recuperar datos de interacción para una Publicación específica, entre ellos:

• El ID o los ID de la Publicación que has solicitado no están disponibles en función del token de autenticación que estás utilizando para recuperar datos en nombre de un tercero.
• El ID o los ID de la Publicación que has solicitado específicamente para el endpoint /totals no son de 90 días o más recientes y, por lo tanto, no están disponibles para devolver las impresiones o las métricas de interacción.
• El ID o los ID de la Publicación que has solicitado ya no están disponibles, lo que suele indicar que se han eliminado o que ya no están disponibles públicamente por otro motivo.

Revisa los diferentes mensajes de error que probablemente recibirás en cualquiera de los casos anteriores.

¿Cómo puedo manejar la limitación de frecuencia con la Engagement API?

Puedes usar la información x-per-minute-limit y x-per-minute-remaining devuelta en el encabezado de la respuesta cuando haces una solicitud a la Engagement API para controlar tu consumo.

x-per-minute-limit indica cuál es tu asignación y x-per-minute-remaining indica cuántas llamadas te quedan.

​

Guía de resolución de errores

Tengo problemas para autenticarme

Asegúrate de revisar nuestras directrices sobre autenticación con la Engagement API.

He enviado la consumer key y el secret correctos, así como el access token y el access token secret, pero se devuelve el siguiente error. ¿Qué puedo hacer?

[
    Your account could not be authenticated. Reason: Unknown Authorization Type;
]

Asegúrate de no usar ningún access token ni secret cuando intentes autenticarte con el endpoint /totals. Esto se debe a que, si incluyes estos tokens y estás intentando obtener contenido de una Publicación que no está asociada con esos tokens, es probable que recibas un error como:

[
    Forbidden to access tweets: 1054424731825229824;
]

​

¿Aún no encuentras lo que necesitas?

Tengo una pregunta que aún no ha sido respondida

Ponte en contacto con el soporte técnico y te responderemos lo antes posible.

​

Referencia de la API

​

POST insights/engagement

​

Métodos

Método	Descripción
POST /insights/engagement/totals	Recuperar el total de impresiones e interacciones para una colección de Tweets.
POST /insights/engagement/historical	Recuperar impresiones e interacciones para una colección de Tweets durante un período de hasta 4 semanas, desde el 1 de septiembre de 2014.
POST /insights/engagement/28hr	Recuperar impresiones e interacciones para una colección de Tweets durante las últimas 28 horas.

​

Autenticación

La Engagement API requiere el uso de HTTPS y admite tanto User Context como OAuth solo de aplicación (Application-Only). La mayoría de las solicitudes a la Engagement API requieren el uso de OAuth de 3 patas (una versión específica de User Context), lo que significa que usas la consumer key y la consumer secret de la App que ha sido registrada y aprobada para el acceso a la Engagement API por tu gestor de cuenta de Twitter, así como el access token y el access token secret de los propietarios del Tweet para llamar al endpoint. Las siguientes solicitudes requieren este tipo de OAuth:

• Cualquier solicitud a /totals para obtener los tipos de métricas Impressions y Engagements, que están limitadas a Tweets propios
• Cualquier solicitud a /28hr
• Cualquier solicitud a /historical

Algunas solicitudes a la Engagement API se pueden realizar usando OAuth solo de aplicación (Application-Only), lo que significa que solo necesitas proporcionar tu consumer key y consumer secret, o un Bearer Token. La siguiente solicitud se puede realizar con este tipo de OAuth:

• Cualquier solicitud a /totals para obtener los tipos de métricas Favorites, Replies, Retweets o Video Views, que se pueden recuperar para cualquier Tweet

Para cualquier solicitud, deberás configurar una App de Twitter y la correspondiente API key usando la consola de administración de apps disponible en developer.x.com.

Ten en cuenta: puedes ver y editar tus Twitter apps existentes a través del Twitter app dashboard si has iniciado sesión en tu cuenta de Twitter en developer.x.com.

Una vez que hayas configurado tu App, el id de la App deberá ser aprobado por tu representante de cuenta para que tu App pueda realizar solicitudes a la Engagement API. Los access tokens deben utilizarse para representar al “usuario actual”, y las solicitudes realizadas en nombre de otro usuario deben firmarse con un token válido. Asegúrate de que estás codificando los caracteres reservados correctamente dentro de las URL y de los cuerpos de las solicitudes POST antes de preparar las cadenas base de la firma OAuth.

Para obtener más información sobre cómo comenzar con OAuth, visita los siguientes enlaces:

• Descripción general de OAuth
• Uso de OAuth de 3 patas, también conocido como User Context
• Uso de OAuth solo de aplicación (Application-Only)

​

POST /insights/engagement/totals

El endpoint totals permite obtener las impresiones e interacciones totales actuales para una colección de hasta 250 Tweets a la vez.

Método de la solicitud	HTTP POST
URL	https://data-api.x.com/insights/engagement/totals
Tipo de contenido	application/json
Compresión	Gzip. Para realizar una solicitud usando compresión con Gzip, envía un encabezado Accept-Encoding en la solicitud de conexión. El encabezado debería verse de la siguiente manera: Accept-Encoding: gzip
Formato de la solicitud POST	Las solicitudes se pueden enviar mediante una petición POST en la que el cuerpo es un objeto JSON que contiene una colección de IDs de Tweet y una agrupación deseada. El POST tiene el formato de un array con los objetos tweets, engagements y groupings. Cada solicitud puede tener un máximo de 250 IDs de Tweet. Un ejemplo de cuerpo de la petición POST es el siguiente: { “tweet_ids”: [ “Tweet ID 1”, “Tweet ID 2”, “Tweet ID 3” ], “engagement_types”: [ “impressions”, “engagements”, “favorites”, “quote_tweets” ], “groupings”: { “grouping name”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } }
id de Tweets	Un array que incluye los ID de los Tweets para los que se recuperarán datos de interacción. Ten en cuenta que solo puedes solicitar datos de Tweets que hayan sido creados por el @handle autenticado. Puedes incluir hasta 250 Tweets por solicitud y los ID de esos Tweets deben representarse como cadenas.
Tipos de interacción	Un array que incluye los tipos de métricas de interacción que se consultarán. El endpoint /totals solo admite los siguientes tipos de interacción: impressions, engagements, favorites, retweets, quote_tweets, replies, video_views. El endpoint /totals permite recuperar impressions y engagements para Tweets creados en los últimos 90 días, y favorites, retweets, quote_tweets, replies y video_views para cualquier Tweet.
Agrupaciones	Los resultados de la Engagement API se pueden devolver en diferentes grupos para adaptarse mejor a tus necesidades. Puedes incluir un máximo de 3 agrupaciones por solicitud. Para cada agrupación, puedes definir un nombre de agrupación personalizado para que sea más fácil hacer referencia a este tipo de agrupación en tu aplicación. Una vez que hayas definido un nombre de agrupación, puedes elegir agrupar por tweet.id y/o engagement.type. Las agrupaciones se aplican de forma secuencial, de modo que puedes cambiar el formato del resultado deseado cambiando el orden de tus valores group_by. Un ejemplo de agrupación que mostrará las métricas separadas por ID de Tweet y tipo de métrica es el siguiente: “groupings”: { “my grouping name”: { “group_by”: [ “tweet.id”, “engagement.type” ] } }
Límite de tamaño de la solicitud POST	Puedes realizar solicitudes para un máximo de 250 ID de Tweets a la vez.
Formato de la respuesta	JSON. El encabezado de la solicitud debe especificar JSON como formato de respuesta.
Límite de uso	Estarás sujeto a límites de frecuencia por minuto, según lo establecido en tu contrato y de acuerdo con tu nivel de acceso.
Ejemplo de solicitud (métricas públicas)	curl —request POST —url https://data-api.x.com/insights/engagement/totals —header ‘accept-encoding: gzip’ —header ‘authorization: Bearer ’ —header ‘content-type: application/json’ —data ’{ “tweet_ids”: [ “1070059276213702656”,“1021817816134156288”,“1067094924124872705” ], “engagement_types”: [ “favorites”,“retweets”,“replies”,“quote_tweets”,“video_views” ], “groupings”: { “perTweetMetricsUnowned”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } } —verbose —compressed
Ejemplo de solicitud	curl —request POST —url https://data-api.x.com/insights/engagement/totals —header ‘accept-encoding: gzip’ —header ‘authorization: OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’ —header ‘content-type: application/json’ —data ’{ “tweet_ids”: [ “1060976163948904448”,“1045709644067471360” ], “engagement_types”: [ “favorites”,“replies”,“retweets”,“video_views”,“impressions”,“engagements” ], “groupings”: { “perTweetMetricsOwned”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } }’ —verbose —compressed
Ejemplo de respuesta (métricas públicas)	{ “perTweetMetricsUnowned”: { “1021817816134156288”: { “favorites”: “530”, “quote_tweets”: “79”, “replies”: “147”, “retweets”: “323”, “video_views”: “0” }, “1067094924124872705”: { “favorites”: “1360”, “quote_tweets”: “29”, “replies”: “56”, “retweets”: “178”, “video_views”: “5754512” }, “1070059276213702656”: { “favorites”: “69”, “quote_tweets”: “5”, “replies”: “7”, “retweets”: “26”, “video_views”: “0” } } }
Ejemplo de respuesta	{ “perTweetMetricsOwned”: { “1045709644067471360”: { “engagements”: “2”, “favorites”: “0”, “impressions”: “47”, “replies”: “0”, “retweets”: “8”, “quote_tweets”: “5”, “video_views”: “0” }, “1060976163948904448”: { “engagements”: “4”, “favorites”: “0”, “impressions”: “148”, “replies”: “1”, “retweets”: “9”, “quote_tweets”: “2”, “video_views”: “0” } } }
id de Tweets no disponibles	Para consultas que incluyan IDs de Tweet que ya no estén disponibles (por ejemplo, porque se hayan eliminado), se devolverán los datos correspondientes para todos los IDs de Tweet disponibles, y los IDs de Tweet no disponibles se indicarán en un array llamado unavailable_tweet_ids. Por ejemplo: { “start”: “2015-11-17T22:00:00Z”, “end”: “2015-11-19T02:00:00Z”, “unavailable_tweet_ids”: [ “323456789” ], “group1”: { “423456789”: { “favorites”: “67”, “replies”: “8”, “retweets”: “26”, “quote_tweets”: “2” } } }

​

POST /insights/engagement/28hr

El endpoint de 28 horas permite obtener impresiones e interacciones de una colección de hasta 25 Tweets en las últimas 28 horas. Este endpoint también permite solicitar todas las métricas individuales compatibles. Para ver la lista completa de métricas compatibles, consulta Disponibilidad de métricas.

Método de la solicitud	HTTP POST
URL	https://data-api.x.com/insights/engagement/28hr
Tipo de contenido	application/json
Compresión	Gzip. Para realizar una solicitud con compresión Gzip, incluye un encabezado Accept-Encoding en la solicitud de conexión. El encabezado debería verse de la siguiente manera: Accept-Encoding: gzip
Formato de la solicitud POST	Las solicitudes se pueden enviar como una solicitud POST, donde el cuerpo es un objeto JSON que contiene una colección de IDs de Tweet y una agrupación deseada. El POST se estructura como un array que contiene los objetos tweets, engagements y groupings. Cada solicitud puede tener un máximo de 25 IDs de Tweet. Un ejemplo de cuerpo de la solicitud POST es el siguiente: { “tweet_ids”: [ “Tweet ID 1”, “Tweet ID 2”, “Tweet ID 3” ], “engagement_types”: [ “impressions”, “engagements”, “url_clicks”, “detail_expands” ], “groupings”: { “grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.hour” ] } } }
IDs de Tweet	Una matriz (array) que incluye los ids de los Tweets para los Tweets sobre los que se consultarán datos de interacción. Ten en cuenta que solo puedes solicitar datos de Tweets que hayan sido creados por el @handle que se está autenticando. El endpoint de 28 horas admite hasta un máximo de 25 Tweets por solicitud, y los ids de los Tweets deben enviarse como cadenas.
Tipos de interacción	Un array de tipos de métricas de interacción que se van a consultar. Para el endpoint de 28 horas, impressions, engagements y todos los tipos individuales de interacción son métricas admitidas. Para ver la lista completa de métricas de interacción admitidas, consulta Engagement Data.
Agrupaciones	Los resultados de la Engagement API se pueden devolver en diferentes grupos para adaptarse mejor a tus necesidades. Puedes incluir un máximo de 3 agrupaciones por solicitud. Para cada agrupación, puedes definir un nombre de agrupación personalizado para que sea más fácil hacer referencia a este tipo de agrupación en tu aplicación. Una vez que hayas definido un nombre de agrupación, puedes optar por agrupar por uno o más de los siguientes valores: tweet.id engagement.type engagement.day engagement.hour Las agrupaciones se aplican de forma secuencial, de modo que puedes cambiar el formato de resultado deseado cambiando el orden de tus valores de group_by. Un ejemplo de agrupación que mostrará las métricas separadas por ID del Tweet, tipo de métrica y día se ve así: “groupings”: { “my grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day” ] } } Las agrupaciones que tienen 4 elementos group_by solo son válidas si usan uno de los dos órdenes siguientes. Las solicitudes que tengan 4 elementos group_by en una sola agrupación que no coincidan con uno de los siguientes órdenes devolverán un error. Además, solo se permitirá una agrupación con 4 elementos group_by por solicitud. “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day”, “engagement.hour” ] “group_by”: [ “engagement.type”, “tweet.id”, “engagement.day”, “engagement.hour” ]
Límite de tamaño de la solicitud POST	Puedes realizar solicitudes para un máximo de 25 ids de Tweet a la vez.
Formato de la respuesta	JSON. El encabezado de la solicitud debe indicar JSON como formato de la respuesta.
Límite de solicitudes	Estarás sujeto a límites de uso por minuto, según lo especificado en tu contrato y de acuerdo con tu nivel de acceso.
Ejemplo de solicitud	curl -X POST “https://data-api.x.com/insights/engagement/28hr” -H ‘Accept-Encoding: gzip’ -H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’ -d ’{ “tweet_ids”: [ “123456789” ], “engagement_types”: [ “impressions”, “engagements” ], “groupings”: { “hourly-time-series”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day”, “engagement.hour” ] } } }‘
Ejemplo de respuesta	{ “inicio”:“2015-09-14T17:00:00Z”, “end”:“2015-09-15T22:00:00Z”, “hourly-time-series”:{ “123456789”:{ “impresiones”:{ “2015-09-14”:{ “17”:“551”, “18”:“412”, “19”:“371”, “20”:“280”, “21”:“100”, “22”:“19”, “23”:“6” }, “2015-09-15”:{ “00”:“5”, “01”:“2”, “02”:“7”, “03”:“3”, “04”:“1”, “05”:“0”, “06”:“0”, “07”:“0”, “08”:“0”, “09”:“0”, “10”:“0”, “11”:“0”, “12”:“0”, “13”:“0”, “14”:“0”, “15”:“0”, “16”:“0”, “17”:“0”, “18”:“0”, “19”:“0”, “20”:“0”, “21”:“0” } }, “interacciones”:{ “2015-09-14”:{ “17”:“0”, “18”:“0”, “19”:“0”, “20”:“0”, “21”:“0”, “22”:“0”, “23”:“0” }, “2015-09-15”:{ “00”:“0”, “01”:“0”, “02”:“0”, “03”:“0”, “04”:“0”, “05”:“0”, “06”:“0”, “07”:“0”, “08”:“0”, “09”:“0”, “10”:“0”, “11”:“0”, “12”:“0”, “13”:“0”, “14”:“0”, “15”:“0”, “16”:“0”, “17”:“0”, “18”:“0”, “19”:“0”, “20”:“0”, “21”:“0” } } } } }
ID de Tweets no disponibles	Para las consultas que incluyan ID de Tweets que ya no estén disponibles (por ejemplo, porque se hayan eliminado), se devolverán los datos correspondientes para todos los ID de Tweets disponibles y los ID de Tweets no disponibles se indicarán en un array llamado unavailable_tweet_ids. Por ejemplo: { “start”: “2015-11-17T22:00:00Z”, “end”: “2015-11-19T02:00:00Z”, “unavailable_tweet_ids”: [ “323456789” ], “group1”: { “423456789”: { “favorites”: “67”, “replies”: “8”, “retweets”: 26 } } }

​

POST /insights/engagement/historical

El endpoint histórico permite recuperar impresiones e interacciones para una colección de hasta 25 Tweets en cualquier período de hasta 4 semanas de duración. Actualmente, no se pueden solicitar a la API datos anteriores al 1 de septiembre de 2014. El endpoint histórico también permite solicitar todas las métricas individuales compatibles. Para ver la lista completa de métricas compatibles, consulta Disponibilidad de métricas.

Método de solicitud	HTTP POST
URL	https://data-api.x.com/insights/engagement/historical
Tipo de contenido	application/json
Compresión	Gzip. Para realizar una solicitud mediante compresión Gzip, envía un encabezado Accept-Encoding en la solicitud de conexión. El encabezado debe tener el siguiente formato: Accept-Encoding: gzip
Formato de la solicitud POST	Las solicitudes se pueden enviar como una solicitud POST cuyo cuerpo es un objeto JSON que contiene un conjunto de IDs de Tweet y una agrupación deseada. El POST se formatea como un arreglo con un objeto tweets, engagements y groupings. Cada solicitud puede tener un máximo de 25 IDs de Tweet. Cada solicitud se puede especificar con fechas de inicio y fin personalizadas de hasta cuatro semanas de duración. { “tweet_ids”: [ “Tweet ID 1”, “Tweet ID 2”, “Tweet ID 3” ], “engagement_types”: [ “impressions”, “engagements”, “url_clicks”, “detail_expands” ], “groupings”: { “grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.hour” ] } } }
Fechas de inicio y fin	Se puede especificar una fecha de inicio y de fin personalizada con los valores start y end como parte de la solicitud. Debe especificar una fecha de inicio y una fecha de fin cuya duración no sea superior a 4 semanas. La fecha de inicio más antigua posible en este momento es el 1 de septiembre de 2014. No se admiten fechas de fin en el futuro. Si no se proporcionan una fecha de inicio y una fecha de fin, la API tomará por defecto las 4 semanas inmediatamente anteriores. La granularidad más baja con la que se pueden devolver datos de la Engagement API es por hora. Para cualquier solicitud realizada con valores de inicio o fin que no caigan exactamente en un límite horario, las solicitudes se redondearán a la hora inclusiva más cercana. Por ejemplo, una solicitud con “start”:“2015-07-01T12:24:00Z” y “end”:“2015-07-10T08:37:00Z” se ajustará a “start”:“2015-07-01T12:00:00Z”,“end”:“2015-07-10T09:00:00Z”.
ID de Tweets	Una matriz que contiene los id de los Tweets para los que se recuperarán datos de interacción. Ten en cuenta que solo puedes solicitar datos de Tweets que hayan sido creados por el @handle utilizado para la autenticación. El endpoint histórico de 4 semanas permite hasta un máximo de 25 Tweets por solicitud, y los id de los Tweets deben representarse como cadenas.
Tipos de interacción	Una matriz que incluye los tipos de métricas de interacción que se van a consultar. Para el endpoint histórico de 4 semanas, impressions, engagements y todos los tipos de interacción individuales son métricas admitidas. Para ver la lista completa de métricas de interacción admitidas, consulta Datos de interacción. Nota: Actualmente hay tres métricas que aparecerán con valor cero para las consultas realizadas antes del 15 de septiembre de 2015: favorites, replies y retweets.
Agrupaciones	Los resultados de la Engagement API se pueden devolver en diferentes grupos para adaptarse mejor a tus necesidades. Puedes incluir un máximo de 3 agrupaciones por solicitud. Para cada agrupación, puedes definir un nombre de agrupación personalizado para que sea más fácil hacer referencia a este tipo de agrupación en tu aplicación. Una vez que hayas definido un nombre de agrupación, puedes elegir agrupar por uno o más de los siguientes valores: tweet.id engagement.type engagement.day engagement.hour Las agrupaciones se aplican de forma secuencial, de modo que puedes cambiar el formato de resultado deseado cambiando el orden de tus valores group_by. Un ejemplo de agrupación que mostrará las métricas separadas por ID de Tweet, tipo de métrica y día tiene el siguiente formato: “groupings”: { “my grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day” ] } } Las agrupaciones que tienen 4 elementos group_by solo son válidas si utilizan uno de los dos órdenes siguientes. Las solicitudes que tengan 4 elementos group_by en una sola agrupación y que no sigan uno de los siguientes órdenes devolverán un error. Además, solo se permitirá una agrupación con 4 elementos group_by por solicitud. “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day”, “engagement.hour” ] “group_by”: [ “engagement.type”, “tweet.id”, “engagement.day”, “engagement.hour” ]
Límite de tamaño de la solicitud POST	Puedes realizar solicitudes para un máximo de 25 id de Tweets a la vez.
Formato de la respuesta	JSON. El encabezado de tu solicitud debe indicar el formato JSON para la respuesta.
Límite de solicitudes	Estarás sujeto a límites de frecuencia por minuto, según se especifique en tu contrato y en función de tu nivel de acceso.
Ejemplo de solicitud	curl -XPOST “https://data-api.x.com/insights/engagement/historical” -H ‘Accept-Encoding: gzip’ -H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’ -d ’{ “start”: “2015-08-01”, “end”: “2015-08-15”, “tweet_ids”: [ “123456789”, “223456789”, “323456789” ], “engagement_types”: [ “impressions”, “engagements”, “url_clicks”, “detail_expands” ], “groupings”: { “types-by-tweet-id”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } }‘
Ejemplo de respuesta	{ “start”: “2015-08-01T00:00:00Z”, “end”: “2015-08-15T00:00:00Z”, “types-by-tweet-id”: { “123456789”: { “impressions”: “0”, “engagements”: “0”, “url_clicks”: “0”, “detail_expands”: “0” }, “223456789”: { “impressions”: “788”, “engagements”: “134”, “url_clicks”: “30”, “detail_expands”: “1323” }, “323456789”: { “impressions”: “4”, “engagements”: “0”, “url_clicks”: “2”, “detail_expands”: “0” } } }
IDs de Tweet no disponibles	Para las consultas que incluyan IDs de Tweet que hayan dejado de estar disponibles (por ejemplo, porque se hayan eliminado), se devolverán los datos correspondientes para todos los IDs de Tweet disponibles, y los IDs de Tweet no disponibles se indicarán en un arreglo llamado unavailable_tweet_ids. Por ejemplo: { “start”: “2015-11-17T22:00:00Z”, “end”: “2015-11-19T02:27:50Z”, “unavailable_tweet_ids”: [ “323456789” ], “group1”: { “423456789”: { “favorites”: “67”, “replies”: “8”, “retweets”: 26 } } }

​

Códigos de respuesta

Estado	Texto	Descripción
200	OK	La solicitud se realizó correctamente.
400	Bad Request	En general, esta respuesta se produce debido a la presencia de JSON no válido en la solicitud, o cuando la solicitud no envía ningún JSON en el cuerpo.
401	Unauthorized	La autenticación HTTP falló porque las credenciales no son válidas. Verifica tus claves y tokens de OAuth.
404	Not Found	El recurso no se encontró en la URL a la que se envió la solicitud, probablemente porque se utilizó una URL incorrecta.
429	Too Many Requests	Tu app ha superado el límite de solicitudes a la API.
500	Internal Server Error	Se produjo un error del lado de Gnip. Vuelve a intentar tu solicitud utilizando un patrón de reintentos con backoff exponencial.
502	Proxy Error	Se produjo un error del lado de Gnip. Vuelve a intentar tu solicitud utilizando un patrón de reintentos con backoff exponencial.
503	Service Unavailable	Se produjo un error del lado de Gnip. Vuelve a intentar tu solicitud utilizando un patrón de reintentos con backoff exponencial.

​

Mensajes de error

En diversos escenarios, en la Engagement API pueden producirse mensajes de error específicos de la situación que tu aplicación debe estar preparada para gestionar. La siguiente tabla incluye ejemplos comunes de estos mensajes de error y cómo deberías interpretarlos. Ten en cuenta que, en muchos casos, la Engagement API devolverá resultados parciales para los datos disponibles con mensajes de error específicos como parte de una respuesta 200 OK con más información.

Mensaje de error	Descripción
"errors":["Your account could not be authenticated. Reason: Access token not found"]	Un error en el componente de autenticación de la solicitud. El “Reason” debería proporcionar información útil para solucionar el error. En los casos en los que no puedas resolverlo, envía el error completo, incluido el “Reason”, a nuestro equipo de soporte.
"errors":["1 Tweet ID(s) are unavailable"],"unavailable_tweet_ids": ["TWEET_IDS"]	El ID de Tweet o los IDs de Tweet que has solicitado ya no están disponibles, lo que normalmente indica que se han eliminado o que ya no están disponibles públicamente por otro motivo.
"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*]	El ID de Tweet o los IDs de Tweet que has solicitado específicamente para el endpoint /totals tienen más de 90 días de antigüedad y, por lo tanto, no están disponibles para devolver las métricas de impresiones o de engagement.
"errors":["Forbidden to access tweets: *TWEET_IDS*"]	El ID de Tweet o los IDs de Tweet que has solicitado no están disponibles en función del token de autenticación que estás utilizando para recuperar datos en nombre de un tercero.