Saltar al contenido principal

​
Descripción general

Empresarial Esta es una API Empresarial disponible únicamente dentro de nuestros niveles de acceso gestionado. Para usar esta API, primero debe configurar una cuenta con nuestro equipo de ventas empresariales. Más información La Engagement API proporciona acceso a métricas de impresiones y de interacción de los Posts. Si bien la mayoría de las métricas y endpoints requieren autenticarse mediante Contexto de usuario de OAuth 1.0a, puede 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 observe diferencias entre los datos mostrados en algunos paneles web de X y los datos reportados en la Engagement API. Estas diferencias se deben a que los paneles web normalmente solo muestran interacciones y/o impresiones ocurridas dentro del rango de tiempo seleccionado. Por ejemplo, un panel web puede mostrar la interacción en Posts dentro del lapso de un mes calendario, mientras que la Engagement API puede mostrar interacciones que quedan fuera del lapso de ese mes, pero dentro del rango de tiempo solicitado. En estos casos, la Engagement API debe considerarse la fuente válida.  

​
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 los Posts deseados
  • Limitado a las siguientes métricas: Impresiones, Interacciones, Favoritos, Respuestas, Retweets, Tweets citados y Reproducciones de video
  • Permite recuperar las métricas de Impressions y Engagements para Posts creados en los últimos 90 días usando Contexto de usuario de OAuth 1.0a
  • Permite recuperar las métricas de Favorites, Retweets, Quote Tweets, Replies y Video Views para any Post usando el token Bearer de OAuth 2.0
  • 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 control y para calcular tasas de interacción en una variedad de @handles
  • Permite solicitar métricas para hasta 250 Posts 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 métricas de interacción individuales que se hayan producido en las últimas 28 horas
  • Los datos pueden agruparse por Post ID y, en series temporales de forma agregada, por día o por hora
  • Ideal para hacer seguimiento del rendimiento del contenido creado recientemente
  • Compatible con todas las métricas disponibles
  • Permite solicitar métricas para hasta 25 Posts por solicitud  

​
Histórico: [/historical]

  • Las solicitudes pueden devolver impresiones, interacciones y un desglose de métricas de interacción individuales del último año, según el momento de la interacción (no el de creación del Post).
  • Las solicitudes admiten parámetros de fecha de inicio y fecha de fin, lo que ofrece flexibilidad para acotar un periodo específico de hasta 4 semanas de duración.
  • Los datos de interacción del Post se limitan a 365 días hacia atrás.
  • Los datos se pueden agrupar por id de Post 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 elaborar una perspectiva histórica del rendimiento de un @handle.
  • Admite todas las métricas disponibles.
  • Permite solicitar métricas para hasta 25 Posts por solicitud.

​
Métricas disponibles

La tabla siguiente describe los tipos de métricas a las que se puede acceder mediante la Engagement API. Consulta nuestra página sobre cómo interpretar las métricas para obtener más información sobre las métricas mencionadas.
MétricaDisponibilidad del endpointSe requiere contexto de usuarioDescripción
impresionesTodoSíUn recuento de cuántas veces se ha visto el Post. Esta métrica solo está disponible para Posts publicados en los últimos 90 días.
interaccionesTodoSíUn recuento de las veces que un usuario ha interactuado con el Post. Esta métrica solo está disponible para Posts publicados en los últimos 90 días.
FavoritosTodoSí - /28 h&/Historial

No: /totals		Un conteo de cuántas veces se ha marcado como favorito el Post.
retuitsTodoSí - /28 h&/Historial

No - /totals		Un recuento de cuántas veces se ha Retuiteado el Post.
cita textual_Tweets/totalsNo - /totalsUn recuento de las veces que un Post se ha Retuiteado con un comentario (también conocido como Quote).
respuestasTodoSí - /28 h&/Historial

No: /totals		Un recuento de cuántas veces se ha respondido al Post.
video_visualizacionesTodoSí - /28 h&/Historial

No - /totals		Recuento de las veces que un video en el Post indicado ha estado al menos un 50 % visible durante dos segundos.

Las visualizaciones de video solo están disponibles para los Posts de 1800 días o menos. Si intenta solicitar visualizaciones de video para cualquier Post de más de 1800 días, recibirá el siguiente objeto en su respuesta, junto con un objeto aparte que contiene cualquier otra métrica que haya solicitado:

“no compatible_para_video_vistas_Tweet_ids”: [“Tweet_ID”]

**Tenga en cuenta:**Es posible que observes una discrepancia entre la métrica de visualizaciones de video que se muestra en las plataformas de X (App 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 reflejan el total de visualizaciones del video agregadas en todas las Posts en las que se haya publicado dicho 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 Retweeted o vuelto a publicar en Posts independientes. Esta métrica no incluye visualizaciones de video en GIFs.
- Las reproducciones de video proporcionadas por los endpoints /28hr y /historical solo incluirán las generadas por el Post específico para el que estás obteniendo métricas. Esta métrica no incluye reproducciones de video en GIF.
multimedia_visualizaciones/28hr /historicalSíUn recuento de todas las visualizaciones (reproducción automática y por clic) de tu contenido multimedia, contabilizadas en videos, GIF e imágenes.
multimedia_interacciones

(antes Media Clicks)		/28hr /historialSíUn recuento de cuántas veces se ha hecho clic en contenido multimedia, como una imagen o un video, dentro del Post.
url_clics/28hr /historicalSíUn recuento de cuántas veces se hizo clic en una URL del Post.
hashtag_clics/28h /historicalSíUn recuento de cuántas veces se hizo clic en un hashtag del Post.
detalle_se expande/28h /históricoSíUn recuento de cuántas veces se hizo clic en el Post para ver más detalles.
enlace permanente_clics/28h /históricoSíUn recuento de cuántas veces se ha hecho clic en el enlace permanente del Post (la página web dedicada a ese Post).
App_instalar_intentos/28hr /historialSíUn recuento de cuántas veces se ha producido un evento de instalación de App desde el Post
App_aperturas/28h /historicalSíUn recuento de cuántas veces se ha producido un evento de App Open desde el Post.
correo electrónico_Tweet/28hr /historicalSíUn recuento de cuántas veces se ha compartido el Post por correo electrónico.
usuario_seguidores/28h /históricoSíUn recuento de cuántas veces se ha seguido al Usuario (autor del Post) a partir de este Post.
usuario_perfil_clics/28h /historialSíUn recuento de cuántas veces el Usuario (autor del Post) ha recibido clics en su perfil desde este Post.

​
Agrupaciones de interacción

Las agrupaciones permiten organizar de forma personalizada las métricas de interacción devueltas. Puede incluir como máximo 3 agrupaciones por solicitud. Puede optar por 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, visite la página Engagement API Grouping en la sección Guides.

​
Guías

​
Guía de introducción para desarrolladores

​
Introducción

El propósito de esta documentación es ofrecer a los desarrolladores una introducción a la integración con la Engagement API. Empezaremos por explicar los “porqués” de la integración 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 de los Posts propios de cualquier cuenta de X de los últimos 90 días, siempre que dicha cuenta haya autorizado tu App para solicitar métricas en su nombre usando 3-legged OAuth. Esta solución potente y fácil de implementar ofrece acceso inmediato a impresiones e interacciones detalladas como clics en URL, clics en #hashtag y muchas más.
  • La Engagement API proporciona métricas agregadas totales de favoritos, Retweets, Quote Tweets, respuestas y visualizaciones de video para cualquier Post. Esto puede utilizarse como una forma eficaz de obtener datos básicos de interacción sobre cualquier Post o colección de Posts.
  • La Engagement API aporta nuevo valor a las plataformas de escucha social, marketing y publicación al permitir a los clientes medir el ROI en X evaluando de forma efectiva el rendimiento del contenido con más de 15 métricas de desempeño.
  • La Engagement API es una API de solicitud/respuesta que permite a los desarrolladores de aplicaciones enviar solicitudes con IDs de Post, métricas deseadas y un intervalo de tiempo, para lo cual la API devuelve data al instante.  
¿Por qué integrar? Casos de uso de ejemplo
  • Comprenda el alcance total de su contenido para ver cuántas personas lo ven. Vea cuántas personas reproducen videos, hacen clic en enlaces, interactúan con hashtags o instalan mis apps.
  • Genere métricas de interacción tanto totales como en series temporales.
  • Comprenda métricas básicas de interacción (favoritos, Retweets, Quote Tweets, respuestas) sobre cualquier Post público.
  • Use estas métricas para determinar qué tipos de Posts funcionan, de modo que pueda publicarlos con más frecuencia y obtener más impresiones y más interacciones con mi contenido.
  • Automatice acciones de marketing (como hacer Retweet de contenido desde otra cuenta propia) cada vez que uno de mis Posts alcance 100 Me gusta u otro umbral.
  • Compare y evalúe mis campañas entre sí como herramienta para pruebas A/B.
  • Analice qué tipo de contenido resuena con mi departamento de atención al cliente para determinar cómo y cuándo responder.
  • Muestre analíticas del contenido publicado 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í hay un caso de estudio que describe una integración de ejemplo: Ahora que hemos explorado los “porqués” de la Engagement API, comencemos 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 REST 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 (sigue los enlaces para más documentación):
  • Arreglo de IDs de Post.
  • Arreglo que especifica los tipos de métricas de interés. Los tipos incluyen elementos como “impressions”, “retweets”, “hashtag_clicks” y “user_follows”.
  • Agrupaciones de interacción, 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 Post. La Engagement API proporciona tres endpoints:
  • Totals - Proporciona totales generales de interacciones para Posts. Algunas métricas están disponibles para todos los Posts, 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 durante hasta cuatro semanas consecutivas para Posts publicados desde el 1 de septiembre de 2014.
El endpoint /totals admite solicitar métricas para hasta 250 Posts por solicitud. Los endpoints /28hour y /historical admiten 25 por solicitud. Después de explicar cómo obtener acceso a la Engagement API, mostraremos cómo realizar una solicitud a la API, daremos 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. De no ser así, comuníquese con su administrador de cuenta Empresarial o solicite acceso Empresarial aquí. El primer paso es crear una App de X usando una cuenta de desarrollador aprobada a través del Portal de desarrolladores. Su administrador de cuenta necesitará el id numérico de la App asociado con esta aplicación para otorgarle acceso. Si necesita solicitar una cuenta de desarrollador, puede hacerlo aquí.
Realizar una solicitud
La buena noticia es que hacer solicitudes a la Engagement API es sencillo. En nuestra solicitud, pediremos el total de Retweets, Quote Tweets, Favoritos y respuestas para los siguientes dos Posts de @XDevelopers:
1/ Hoy compartimos nuestra visión para el futuro de la plataforma X APIhttps://t.co/XweGngmxlP — Twitter Dev (@TwitterDev) 6 de abril de 2017
No te pierdas los Posts sobre tu Post. Ahora en iOS puedes ver los Retweets con comentarios, todo 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 consta de estos dos id de Post colocados en un arreglo, un arreglo de tipos de interacción de interés y un objeto JSON “groupings” con nombre personalizado 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 obtener estas métricas totales, enviamos mediante POST esta solicitud 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 realizar solicitudes, nos autenticamos con OAuth, tema que trataremos con más detalle en la siguiente sección. La API devuelve la siguiente carga: 
{
  "grouping name": {
    "1260294888811347969": {
      "favoritos": "17111",
      "tweets_citados": "3254",
      "respuestas": "1828",
      "retweets": "5218"
    },
    "850006245121695744": {
      "favoritos": "492",
      "tweets_citados": "66",
      "respuestas": "42",
      "retweets": "324"
    }
  }
}
Tenga en cuenta que la respuesta incluye las métricas solicitadas siguiendo la estructura definida por las “agrupaciones”, con las métricas primero organizadas por id de Post y, en el siguiente nivel, por tipo de interacción. Fue bastante sencillo. Si está comenzando con la autenticación mediante OAuth, consulte 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 usas OAuth (quizá con otras X APIs), probablemente estés utilizando un paquete de OAuth específico del lenguaje que abstrae todos los detalles complejos. 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 encontrar un paquete de OAuth para tu lenguaje de integración preferido y comenzar por ahí. Con estos paquetes, el proceso de autenticación normalmente implica configurar tus claves y tokens, crear algún tipo de objeto HTTP y luego 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 utilizando la gema de Ruby ‘oauth’ y realizar una solicitud POST: 
require 'oauth'

#Ensamblar solicitud JSON (como arriba).
request = make_json_request()

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

#Crear objeto de App habilitado para OAuth.
app = OAuth::AccessToken.from_hash(consumer, token)
#Realizar solicitud POST.
result = app.post(“/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"})
La Engagement API admite autenticación tanto solo de aplicación como con contexto de usuario. Si recopilas métricas de interacción de Posts públicos que no te pertenecen con el endpoint /totals, 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 haga una solicitud a la API “en nombre de otro usuario”, utilizando tokens asociados al usuario. Si generas métricas de interacción para Posts propios, es decir, Posts publicados por un usuario para el que tienes tokens de usuario, realizarás solicitudes con 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 suelen proporcionarse mediante el proceso ‘Sign-in with X’ o adquirirse 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, no caducan y pueden usarse con la Engagement API para realizar solicitudes en su nombre, siempre que el usuario no restablezca sus tokens ni cambie su contraseña; en ese caso, deberá proporcionarte los nuevos tokens. Puedes consultar qué métricas requieren qué tipo de Autenticación en esta tabla.

​
Selección de un endpoint de la Engagement API

La Engagement API ofrece tres endpoints distintos:
  • Totales - proporciona totales generales de métricas seleccionadas de Posts “propios” o “no propios”. Algunas métricas están disponibles para todos los Posts, mientras que otras solo para los Posts publicados en los últimos 90 días. Admite 250 Posts por solicitud.
  • 28 horas - proporciona métricas de Engagement en series temporales para Posts “propios” de las últimas 28 horas. Admite 25 Posts por solicitud.
  • Histórico - proporciona métricas de Engagement en series temporales durante hasta cuatro semanas consecutivas para Posts “propios” publicados desde el 1 de septiembre de 2014. Admite 25 Posts por solicitud.  
Cada endpoint tiene características propias. Ya sea que planee usar los tres o esté tratando de decidir cuál se ajusta mejor a su caso de uso, es importante comprender las diferencias entre ellos. A continuación, presentamos algunos conceptos clave, analizamos con más detalle los tres endpoints y luego mostramos casos de uso de ejemplo que, en términos generales, se corresponden con un endpoint específico. Esperamos que esta información le ayude a integrar los tres de manera más eficiente o a decidir cuál endpoint único se ajusta mejor a su objetivo.  

​
Conceptos clave

Hay varios conceptos clave que ayudan a ilustrar las distintas funciones y los datos que proporcionan los tres endpoints de la Engagement API.  
Métricas de impresiones y participación
Las impresiones representan la cantidad de veces que un Post determinado se ha visto en la plataforma X en un contexto orgánico. No se incluyen las impresiones generadas por Posts que se ven en un contexto Promocionado o de Pago. Antes de la Engagement API, las impresiones de un Post representaban solo una medida de visualizaciones potenciales. Se basaban en contar a los seguidores de la cuenta del autor y a los de cualquier cuenta que hiciera Retweet del contenido. No tenían en cuenta la situación habitual en la que un usuario no llega a ver el Post. Las métricas de impresiones generadas por la Engagement API constituyen una medida real de la cantidad de veces que un Post se ha renderizado para su visualización. Si un seguidor de tu cuenta no ve tu Post, no cuenta como una impresión. La Engagement API proporciona métricas sobre 14 tipos únicos de métricas de participación, cada uno de los cuales representa una acción distinta que un usuario puede realizar cuando se le presenta un Post. Estas incluyen hacer Retweet, dar Like, 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 de Participaciones.
Contenido de X propio y ajeno
Engagement establece una distinción clara entre Posts propios y ajenos. Los Posts propios son aquellos publicados desde tu cuenta o aquellos para los que has obtenido permiso para solicitar datos de Engagement. Como en otras X API, obtienes permiso cuando otros usuarios/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 “Sign in with X”. El endpoint /totals proporciona datos de engagement tanto para Posts propios como ajenos. En el caso de los Posts ajenos, puedes solicitar las métricas de engagement que están disponibles públicamente en la interfaz de un Post: Favorite, Retweet y Reply. Para estas métricas, lo que la Engagement API aporta es la capacidad de recuperarlas a escala de forma automatizada. Para los Posts propios, el endpoint /totals también proporciona las métricas Impression y Engagement (total). Los endpoints /28hr y /historical proporcionan métricas solo para Posts propios, lo que significa que debes incluir el contexto de usuario al realizar la solicitud a estos endpoints.
Datos de interacción totales y de series temporales
El endpoint /totals proporciona, como su nombre lo indica, únicamente totales globales para sus tipos de interacción. Sus cifras representan los totales actualizados desde que se publicó el Post. Si un Post se acaba de publicar y solicitas sus métricas repetidamente, 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 interacción pueden consolidarse en datos diarios u horarios.    Consulta nuestra documentación sobre agrupaciones de interacción para ver 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 suele corresponder a distintos tipos de casos de uso. Para ayudarle a decidir qué endpoint se ajusta mejor a su caso concreto, a continuación se incluyen algunos ejemplos de declaraciones de usuarios y el endpoint que mejor las 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 Post, no solo para Posts propios.
  • Quiero comparar el rendimiento con un competidor.
  • Quiero hacer seguimiento de estadísticas básicas de interacción para un hashtag o campaña que incluya Posts que no me pertenecen.
  • No necesito data desglosada por día u hora; solo necesito el total actual cuando realizo una solicitud.
  • Necesito una única métrica para mostrar en un informe o panel y no quiero almacenar ningún dato.
  • Quiero mostrar data al cargar la página, y solo necesito hacer una solicitud y obtener una respuesta.
  • Necesito acceso para obtener data de cientos de miles o millones de Posts por día.  
/28hr
  • Necesito acceso a los 17 tipos de métricas.
  • Quiero mostrar data de Posts muy recientes publicados en las últimas 28 horas.
  • Tengo un proceso que se ejecuta una vez al día para obtener la data que me interesa y solo necesito la data del último día.
  • Necesito que las métricas estén desglosadas por día u hora.
  • Quiero mostrar series temporales de actividad por hora en un panel.
  • Necesito acceso de alto volumen para cientos de miles de Posts por día.
  • Tengo capacidades de almacenamiento y puedo actualizar la data una vez al día y mantener un conteo acumulado.  
/historical
  • Necesito acceso a los 17 tipos de métricas.
  • Necesito obtener datos históricos de Posts creados desde septiembre de 2014.
  • Quiero mostrar análisis históricos detallados que comparen campañas.
  • Necesito que las métricas se desglosen por día u hora.
  • No necesito un nivel alto de acceso a la Engagement API y solo necesito obtener data para unos cientos o miles de Posts por día.

​
Características clave de la Engagement API

  • API RESTful que entrega datos JSON y admite solicitudes POST con cuerpos JSON.
  • Tipos de solicitudes: Las apps 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 están disponibles para los Posts propiedad de un usuario que haya autorizado tu App mediante OAuth de 3 pasos. Debes usar los tokens de acceso de ese usuario al realizar tu solicitud.
    • OAuth 2.0 Bearer Token: Métricas seleccionadas (Retweets, Quote Tweets, Replies, Favorites y Video Views) están disponibles para cualquier Post público.
  • Metadatos y estructura de la solicitud: Los datos de la solicitud son un objeto JSON que consta de un array de Post IDs, un array de tipos de engagement y una estructura de agrupación de engagement.
  • Posts 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 que se publicó el Post. Impressions y Engagements están disponibles para Posts publicados en los últimos 90 días, mientras que Retweets, Quote Tweets, Replies, Favorites y Video Views están disponibles para todos los Posts.
    • /28hr — Últimas 28 horas a partir del 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. Su disponibilidad depende del endpoint y, si se solicita desde el endpoint /totals, de si los Posts tienen permisos del usuario.
    • Endpoint /totals:
      • Todos los Posts: Favorites, Retweets, Quote Tweets, Replies y Video Views
      • Requiere Contexto de usuario de OAuth 1.0a: Impressions, Engagements, Favorites, Replies y Retweets
    • Endpoints /28hr y /historical (requiere Contexto de usuario de OAuth 1.0a con el Access Token del propietario del Post): 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 por 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 app cliente que pueda enviar solicitudes HTTP a la Engagement API para devolver métricas de engagement para el Post ID incluido en la solicitud.
  • Limitaciones
  • Las Video Views solo están disponibles para Posts con una antigüedad de 1800 días o menos.

​
Autenticación con la Engagement API

Tenga en cuenta:  X debe habilitar el acceso a la Engagement API para su App de desarrollador antes de que pueda empezar a usar la API. Para ello, asegúrese de compartir el App ID que pretende usar para fines de autenticación con su account manager o con el 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 “solo aplicación”) le permite acceder a métricas de interacción públicas. Este método de autenticación se puede usar para obtener los totales de Favorites (también llamados Likes), Retweets, Quote Tweets, Replies y reproducciones de video para cualquier Post público al realizar solicitudes al /totals endpoint.  OAuth 1.0a (también conocido como “contexto de usuario”) le permite realizar 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, debe incluir los Access Tokens (Access Token y Secret) del usuario propietario del Post o del recurso protegido de interés. Si no proporciona los Access Tokens de usuario correctos al solicitar datos de usuario protegidos, la Engagement API devolverá un error 403 Forbidden. La Engagement API no le permitirá obtener datos de interacción de protected Posts, incluso si se autentica en nombre del usuario propietario de esos Posts. Intentarlo devolverá un error 400 Bad Request, con el mensaje "Tweet ID(s) are unavailable". Si envía una solicitud en nombre de su propia cuenta de X (es decir, la cuenta propietaria del App de desarrollador), puede generar los Access Tokens necesarios directamente desde el Portal de desarrolladores, en la pestaña “Keys and tokens” del App de desarrollador. Si realiza una solicitud en nombre de otro usuario, deberá usar el flujo OAuth de 3 pasos para obtener los Access Tokens 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 con OAuth 1.0a, consulte el código de ejemplo en Python de XDevelopers para la Engagement API.

​
Cambios recientes en la Engagement API

La Engagement API ofrece métricas invaluables de impresiones e interacción que le permiten supervisar el rendimiento de su actividad en X. En nuestro esfuerzo continuo por permitir decisiones de marketing basadas en nuestros datos, nos complace compartir cambios recientes en la Engagement API que aportan mayor coherencia con las métricas en toda X.   Recientemente implementamos cambios para modernizar la Engagement API y utilizar la misma metodología de agregación de métricas empleada por el panel de analíticas de X (analytics.x.com). Adoptamos un enfoque cuidadoso para minimizar los cambios incompatibles en la API al implementar estas nuevas métricas y desplegamos el primer conjunto de cambios el 9 de octubre de 2017. Estos cambios mejoran la coherencia en todos los lugares donde usted o sus clientes puedan supervisar su rendimiento en X. Consulte a continuación el detalle de los cambios:
MetricChange
engagementsActualizamos las métricas que se suman a las interacciones totales para mantener coherencia con el panel de analíticas de Post. Engagements mide “veces que las personas interactuaron con este Post”.

Para los Posts que incluyen medios como un video o un GIF, la métrica engagements ya no incluirá visualizaciones de medios. Las visualizaciones de medios ahora se pueden consultar en una nueva métrica, media_views.
media_clicks*Esta métrica ha sido reemplazada por una nueva métrica llamada “media_engagements”.
video_viewsA partir del 6 de julio de 2018, esta métrica está disponible para Posts “no propios” mediante el endpoint /totals. Esto significa que puede acceder a las visualizaciones de video de todos los Posts usando autenticación de solo App. 

Solo puede solicitar visualizaciones de video con una antigüedad menor de 1800 días. Si intenta solicitarlas para un Post con más de 1800 días, recibirá lo siguiente:

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

Tenga en cuenta que difiere de media_views en que video_views se basa en el estándar MRC de 50% del video en pantalla durante al menos dos segundos.

Además, tenga en cuenta que puede observar una discrepancia entre la métrica de visualizaciones de video mostrada en las plataformas propias y operadas por X (aplicación móvil y sitio web) y el número que recibe mediante los endpoints /28hr y /historical.

* Las visualizaciones de video mostradas en la interfaz de usuario de X y que se entregan mediante el endpoint /totals presentarán la visualización de video agregada en todos los Posts en los que se haya publicado el video en cuestión. Esto significa que la métrica mostrada en la IU incluye las visualizaciones combinadas de cualquier instancia en que el video haya sido Retuiteado o vuelto a publicar en Posts separados.
* Las visualizaciones de video proporcionadas por los endpoints /28hr y /historical solo incluirán aquellas generadas por el Post específico para el que está extrayendo métricas.
media_viewsIncluye todas las visualizaciones (reproducción automática y por clic) de sus medios contabilizadas en videos, vines, GIF e imágenes.

Tenga en cuenta que los Posts con imágenes no muestran la métrica media_views en el panel de analíticas, pero sí se devolverá en la Engagement API.
media_engagements*Incluye la cantidad de clics en sus medios en videos, vines, GIF e imágenes. Esta métrica sustituye a media_clicks.
quote_tweetsA partir del 7 de julio de 2020, esta métrica está disponible para Posts “no propios” mediante el endpoint /totals. Esto significa que puede acceder al recuento de Quote Post para todos los Posts usando autenticación de solo App.

​
Interpretación de las métricas

Nota: Es posible que observes diferencias entre los datos informados en algunos paneles web de X y los datos informados en la Engagement API. Estas diferencias se deben a que los paneles web suelen mostrar únicamente interacciones y/o impresiones que ocurrieron dentro del período de tiempo seleccionado. Por ejemplo, un panel web puede mostrar interacciones en Posts dentro de un mes calendario, mientras que la Engagement API puede mostrar interacciones que quedan fuera de ese mes pero 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 e interacción de tipo orgánico. Las impresiones representan la cantidad de veces que un Post determinado se ha visto en la plataforma X en un contexto orgánico. Las impresiones generadas por Posts que se ven en un contexto promocionado o de pago no están incluidas. Las interacciones representan la cantidad de veces que un espectador interactuó con un Post determinado tanto en contextos orgánico como promocionado. Las interacciones incluyen, entre otras, Retweets, Favoritos, Respuestas, clics en URL, clics en hashtags, clics en menciones y visualizaciones de medios. Para ver la lista completa de acciones de interacción incluidas, consulta la sección Engagement Data. Para calcular una tasa básica de interacción, utiliza el número total de interacciones dividido por el número total de impresiones de un Post determinado durante el periodo que estás analizando. Los datos de impresiones e interacción solo se pueden recuperar para Posts de @handles propios o de @handles que hayan autorizado tu App a ver detalles sobre sus Posts. Internamente, la Engagement API realizará un seguimiento del número de @handles únicos que se han solicitado con respecto al límite de @handles contratado. Se recomienda también hacer un seguimiento del uso de solicitudes de @handle en el lado del cliente a lo largo del mes.  

​
Métricas de video

Existen un par de métricas diferentes que representan impresiones de medios en X. La primera es nuestra métrica de vistas de video, que se basa en el estándar del MRC: 50% del video visible durante al menos dos segundos. La segunda es Vistas de medios, que incluye todas las visualizaciones (reproducción automática y por clic) de tu contenido, contabilizadas en videos, Vines, GIFs e imágenes. La métrica de vistas de video está disponible para Posts propios a través de los endpoints /28hour y /historical, así como para todos los Posts no propios a través del endpoint /totals. Si bien la métrica de vistas de video en la interfaz de usuario de X utiliza el mismo estándar del MRC, ten en cuenta que puede haber una discrepancia entre la métrica mostrada en las plataformas propiedad de y operadas por X (app móvil y sitio web) y el número que recibes a través de los distintos endpoints del Engagement API.
  • Las vistas de video proporcionadas por el endpoint /totals y la interfaz de usuario de X mostrarán las vistas de video agregadas en todos los Posts en los que se haya publicado el video en cuestión. Esto significa que la métrica entregada vía /totals y mostrada en la UI de X incluye las vistas combinadas de cualquier instancia en la que el video haya sido Retwitteado o vuelto a publicar en Posts separados.
  • Las vistas de video proporcionadas por los endpoints /28hour y /historical del Engagement API solo incluirán aquellas generadas por el Post específico para el cual estás obteniendo métricas.
Ten en cuenta que no proporcionamos vistas de video para Posts con más de 1800 días. En su lugar, proporcionamos un objeto que enumera los Posts que superan los 1800 días. Aun así, recibirás todas las demás métricas de tus Posts solicitados en un objeto independiente. Aquí tienes un ejemplo de respuesta: 
{
  "unsupported_for_video_views_tweet_ids": [
    "479311209565413376",
    "477139122520219648"
  ],
  "nombre de agrupación": {
    "479311209565413376": {
      "favoritos": "69",
      "impresiones": "1692",
      "retuits": "142",
      "vistas_de_video": "0"
    },
    "477139122520219648": {
      "favoritos": "10",
      "impresiones": "1023",
      "retuits": "6",
      "vistas_de_video": "0"
    },
    "1397568983931392004": {
      "favoritos": "268",
      "impresiones": "26803",
      "retuits": "56",
      "vistas_de_video": "17902"
    }
  }
}
La métrica Media Views solo está disponible para Posts propios en los endpoints /28hour y /historical.

​
Agrupaciones de la Engagement API

Las agrupaciones permiten organizar de forma personalizada las métricas de interacción devueltas. Puedes incluir un máximo de 3 agrupaciones por solicitud. Puedes optar por 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, por lo que puedes cambiar el formato de los resultados cambiando el orden de tus valores de group_by. Las agrupaciones que contengan cuatro valores de 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 desea generar totales generales por tipo de métrica, incluya la siguiente especificación de “agrupaciones” como parte de su solicitud (y consulte la página de Referencia de la API para obtener más información sobre cómo compilar solicitudes): 
{
  "engagement_types": [
    "favoritos",
    "respuestas",
    "retweets"
  ],
  "groupings": {
    "Totales generales": {
      "group_by": [
        "engagement.type"
      ]
    }
  }
}
Con este agrupamiento, la respuesta JSON de la Engagement API incluirá un atributo de nivel raíz “Grand Totals” que contiene los totales globales por tipo de métrica: 
{
  "Totales generales": {
    "me gusta": "12",
    "respuestas": "2",
    "retuits": "2"
  }
}
Para generar una serie temporal de 4 horas de métricas para un único Post, agrupada por ids de Post, la siguiente especificación de Grouping formarí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 este agrupamiento, la respuesta JSON de la Engagement API incluirá un atributo de nivel raíz “Tweets_MetricType_TimeSeries” que contiene las métricas desglosadas primero por id del Post, luego por tipo de métrica, y la correspondiente serie temporal por hora: 
{
  "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

Empresarial

​
API de Engagement

El acceso a la API de Engagement se ofrece mediante una suscripción Empresarial. Complete este formulario para ponerse en contacto con nuestro equipo de ventas.
Si su contrato incluye un límite en la cantidad de handles únicos que se pueden usar con la API de Engagement, el sistema interno de X llevará un registro del número de usuarios autenticados que son propietarios de Posts consultados con la API de Engagement. Los clientes también deben llevar un control de este número único en el lado del cliente. Actualmente, no existe una API ni una interfaz para consultar el uso de @handle en la API de Engagement. El sistema no bloqueará excedentes si se solicitan más @handles de los contratados. Al final del mes de facturación, el número de @handles únicos consultados se compara con el monto contratado y se cobrará el excedente conforme a los términos del contrato.
Actualmente, no existe una API ni una interfaz para consultar el uso de @handle en la API de Engagement. El sistema no bloqueará excedentes si se solicitan más @handles de los contratados. Al final del mes de facturación, el número de @handles únicos consultados se compara con el monto contratado y se cobrará el excedente conforme a 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 métricas de engagement. ¿Por qué sucede esto?Es lo esperado. El campo de metadatos engagements puede no correlacionarse siempre con la suma de todas las métricas individuales de engagement devueltas por la API. Esto se debe a que el campo engagements puede incluir interacciones adicionales que no tienen métricas específicas desglosadas en el payload. Dicho de otro modo, sumar todos los totales de métricas de engagement puede no igualar el valor que ve en el campo engagements que se devuelve en el payload.Puede considerar el campo de metadatos engagements como cualquier clic o interacción realizada en el Post.  El campo url_clicks en la respuesta del payload devuelve un número, aunque el Post no tiene una URL. ¿Cómo es posible?Puede deberse a que un Post que contiene, por ejemplo, un hashtag (que crea un enlace a otra página) cuente como un clic de URL si un usuario hace clic en él.  
Hay varias razones por las que quizá no pueda obtener datos de engagement para un Post específico, entre ellas:
  • El id del Post o los ids del Post que solicitó no están disponibles según el token de Autenticación que está utilizando para obtener datos en nombre de un tercero.
  • El id del Post o los ids del Post que solicitó para el endpoint /totals no son de 90 días o más recientes y, por lo tanto, no están disponibles para devolver impresiones o métricas de engagement.
  • El id del Post o los ids del Post que solicitó ya no están disponibles, lo que generalmente indica que se han eliminado o que ya no están disponibles públicamente por otro motivo.
Revise los diferentes mensajes de error que probablemente recibirá en cualquiera de los casos anteriores.
Puede usar la información x-per-minute-limit y x-per-minute-remaining devuelta en el encabezado de la respuesta cuando realice una solicitud a la API de Engagement para monitorear su consumo.x-per-minute-limit indica cuál es su asignación y x-per-minute-remaining indica cuántas llamadas le quedan.

​
Guía de resolución de errores

Asegúrate de revisar nuestras directrices sobre Autenticación con la Engagement API.
[
    Your account could not be authenticated. Reason: Unknown Authorization Type;
]
Asegúrate de no usar tokens de acceso ni secretos cuando intentes autenticarte con el endpoint /totals. Esto se debe a que, si incluyes estos tokens y estás intentando extraer contenido de un Post no asociado a ellos, es probable que recibas un error como:
[
    Forbidden to access tweets: 1054424731825229824;
]

​
¿Aún no encuentras lo que buscas?

Comunícate con soporte técnico y te responderemos a la brevedad.

​
Referencia de la API

​
POST insights/engagement

​
Métodos

MétodoDescripción
POST /insights/engagement/totalsRecupera el total de impresiones y de interacciones para una colección de Tweets.
POST /insights/engagement/historicalRecupera impresiones e interacciones para una colección de Tweets durante un período de hasta 4 semanas, con cobertura retroactiva hasta el 1 de septiembre de 2014.
POST /insights/engagement/28hrRecupera impresiones e interacciones para una colección de Tweets de las últimas 28 horas.

​
Autenticación

La Engagement API requiere el uso de HTTPS y admite tanto User Context como Application-Only OAuth. La mayoría de las solicitudes a la Engagement API requieren 3‑Legged OAuth (una variante específica de User Context), lo que significa que debes usar la consumer key y el consumer secret de la App registrada y aprobada para acceder a la Engagement API por tu account manager 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étrica 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 con Application-Only OAuth, 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étrica 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 mediante el 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 app ID deberá ser aprobado por tu account representative para que tu App pueda realizar solicitudes a la Engagement API. Los access tokens deben usarse para representar al “usuario actual”, y las solicitudes realizadas en nombre de un usuario diferente deben firmarse con un token válido. Asegúrate de codificar los caracteres reservados correctamente en las URL y en los cuerpos de POST antes de preparar las base strings de la firma OAuth. Para obtener más información sobre cómo comenzar con OAuth, visita los siguientes enlaces:

​
POST /insights/engagement/totals

El endpoint totals permite obtener las impresiones e interacciones totales actuales de una colección de hasta 250 Tweets a la vez.
Método de solicitudHTTP POST
URLhttps://data-api.x.com/insights/engagement/totals
Tipo de contenidoapplication/json
CompresiónGzip. Para realizar una solicitud con compresión Gzip, envía el encabezado Accept-Encoding en la solicitud de conexión.
El encabezado debería tener el siguiente aspecto:

Accept-Encoding: gzip
Formato de PostLas solicitudes se pueden enviar como una solicitud 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 se formatea como una matriz con unatweets,interacciones, yagrupacionesobjeto. Cada solicitud puede incluir un máximo de 250 IDs de Tweet.

Un ejemplo de cuerpo de la solicitud POST es:


{
“Tweet_ids”: [
“ID de Tweet 1”,
“ID de Tweet 2”,
“ID de Tweet 3”
],
“interacción_Tipos”: [
“impresiones”,
“interacciones”,
“favoritos”,
“cita textual_Tweets”
],
“agrupaciones”:{
“nombre del grupo”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”
]
}
}
}
ids de TweetUna matriz que incluye los id de los Tweets para los que se consultará información de interacción. Tenga en cuenta que solo puede solicitar datos de Tweets creados por el @handle autenticado. Se pueden incluir hasta 250 Tweets por solicitud y los id de los Tweets deben representarse como cadenas.
Tipos de interacciónUna matriz que incluye los tipos de métricas de interacción que se consultarán. El endpoint Totals admite únicamente los siguientes tipos de interacción:impresiones,interacciones,favoritos,retweets,quote_tweets,replies,video_views.
El/totalsel endpoint permite recuperarimpresionesyinteraccionespara los Tweets creados en los últimos 90 días yfavoritos,retuits,quote_tweets,respuestas, yvideo_viewspara cualquier Tweet.
AgrupacionesLos resultados de la Engagement API pueden devolverse en distintos grupos para ajustarse mejor a sus necesidades. Puede incluir un máximo de 3 agrupaciones por solicitud.

Para cada agrupación, puede definir un nombre personalizado para facilitar la referencia a este tipo de agrupación en su aplicación.

Una vez que hayas definido un nombre para el grupo, puedes optar por agrupartweet.idy/oengagement.type.

Las agrupaciones se aplican de forma secuencial, por lo que puedes cambiar el formato de resultado deseado modificando el orden de tu agrupación_por valores. Un ejemplo de agrupación que mostrará métricas separadas por id de Tweet y por tipo de métrica sería:


“agrupaciones”:{
“mi nombre de grupo”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”
]
}
}
Límite de tamaño de PostSe pueden realizar solicitudes con un máximo de 250 IDs de Tweet a la vez.
Formato de la respuestaJSON. El encabezado de su solicitud debe especificar el formato JSON para la respuesta.
Límite de velocidadSe aplicarán límites de tasa por minuto, según lo estipulado en tu contrato y de acuerdo con tu nivel de acceso.
Ejemplo de solicitud (métricas públicas)curl —request POST
—urlhttps://data-api.x.com/insights/engagement/totals
—header’accept-encoding: gzip’
—header’autorización: Bearer’
—header’content-type: application/json’
—data’{
“Tweet_ids”: [
“1070059276213702656”,“1021817816134156288”,“1067094924124872705”
],
“interacción_tipos”: [
“Favoritos”,“retuits”,“respuestas”,“cita textual_Tweets”,“video_visualizaciones”
],
“agrupaciones”:{
“perTweetMetricsUnowned”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”
]
}
}
}
—verbose
—compressed
Ejemplo de solicitudcurl —request POST
—urlhttps://data-api.x.com/insights/engagement/totals
—header’accept-encoding: gzip’
—header’autorización: OAuth oauth_consumidor_key=“consumer-key-for-App”,oauth_nonce=“nonce-generado”,oauth_firma=“firma-generada”,oauth_firma_method=“HMAC-SHA1”, OAuth_timestamp=“marca-de-tiempo-generada”,oauth_token=“token-de-acceso-para-usuario-autorizado”, OAuth_version=“1.0”’
—header’content-type: application/json’
—data’{
“Tweet_ids”: [
“1060976163948904448”,“1045709644067471360”
],
“engagement_Tipos”: [
“Favoritos”,“respuestas”,“retuits”,“video_visualizaciones”,“impresiones”,“interacciones”
],
“agrupaciones”:{
“perTweetMetricsOwned”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”
]
}
}
}’
—verbose
—compressed
Ejemplo de respuesta (métricas públicas){
“perTweetMetricsUnowned”:{
“1021817816134156288”:{
“favoritos”:“530”,
“cita textual_Tweets”:“79”,
“respuestas”:“147”,
“retuits”:“323”,
“video_visualizaciones”:“0”
},
“1067094924124872705”:{
“favoritos”:“1360”,
“cita textual_Tweets”:“29”,
“respuestas”:“56”,
“retuits”:“178”,
“video_visualizaciones”:“5754512”
},
“1070059276213702656”:{
“Favoritos”:“69”,
“cita textual_Tweets”:“5”,
“respuestas”:“7”,
“retuits”:“26”,
“video_visualizaciones”:“0”
}
}
}
Ejemplo de respuesta{
“perTweetMetricsOwned”:{
“1045709644067471360”:{
“interacciones”:“2”,
“favoritos”:“0”,
“impresiones”:“47”,
“respuestas”:“0”,
“retweets”:“8”,
“cita textual_Tweets”:“5”,
“video_visualizaciones”:“0”
},
“1060976163948904448”:{
“interacciones”:“4”,
“Favoritos”:“0”,
“impresiones”:“148”,
“respuestas”:“1”,
“retuits”:“9”,
“cita textual_Tweets”:“2”,
“video_visualizaciones”:“0”
}
}
}
id de Tweets no disponiblesPara las consultas que incluyan IDs de Tweet que ya no estén disponibles (p. ej., porque se eliminaron), se devolverán los datos correspondientes para todos los IDs de Tweet disponibles, y los IDs de Tweet no disponibles se incluirán en una matriz llamadaunavailable_tweet_ids. Por ejemplo:

{
“Comenzar”:“2015-11-17T22:00:00Z”,
“final”:“2015-11-19T02:00:00Z”,
“no disponible_Tweet_ids”: [
“323456789”
],
“grupo1”:{
“423456789”:{
“Favoritos”:“67”,
“respuestas”:“8”,
“retweets”:“26”,
“cita textual_Tweets”:“2”
}
}
}

​
POST /insights/engagement/28hr

El endpoint de 28 horas permite obtener impresiones e interacciones de una colección de hasta 25 Tweets durante las últimas 28 horas. 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 solicitudPOST HTTP
URLhttps://data-api.x.com/insights/engagement/28hr
Tipo de contenidoapplication/json
CompresiónGzip. Para realizar una solicitud con compresión Gzip, incluye el encabezado Accept-Encoding en la solicitud de conexión.
El encabezado debería verse de la siguiente manera:

Accept-Encoding: gzip
Formato de PostLas solicitudes pueden enviarse como una solicitud POST cuyo cuerpo es un objeto JSON que contiene una colección de id de Tweet y una forma de agrupación deseada. El POST se formatea como una matriz con untweets,interacciones, yagrupacionesobjeto. Cada solicitud puede incluir un máximo de 25 IDs de Tweet.

Un ejemplo de cuerpo de la solicitud POST es:


{
“Tweet_ids”: [
“ID de Tweet 1”,
“ID de Tweet 2”,
“ID de Tweet 3”
],
“interacción_Tipos”: [
“impresiones”,
“interacciones”,
“URL_clics”,
“detalle_amplía”
],
“agrupaciones”:{
“nombre del grupo”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”,
“interacción.hora”
]
}
}
}
id de TweetUna matriz que incluye los IDs de Tweet de los Tweets para los que se consultarán datos de interacción. Tenga en cuenta que solo puede solicitar datos de Tweets creados por el @handle autenticado. El endpoint de 28 horas admite hasta 25 Tweets por solicitud, y los IDs de Tweet deben representarse como cadenas.
Tipos de interacciónUna matriz con los tipos de métricas de interacción que se consultarán.

Para el endpoint de 28 horas,impresiones,interacciones, y todos los tipos de interacción individuales son métricas admitidas. Para ver la lista completa de métricas de interacción admitidas, consultaDatos de engagement.
AgrupacionesLos resultados de la Engagement API pueden devolverse en distintos grupos para ajustarse mejor a sus necesidades. Puede incluir un máximo de 3 agrupaciones por solicitud.

Para cada agrupación, puedes definir un nombre personalizado para facilitar la referencia a este tipo de agrupación en tu aplicación. Una vez definido el nombre, puedes optar por agrupar por uno o más de los siguientes valores:
tweet.id
engagement.type
engagement.day
interaccion.hora
Los agrupamientos se respetan en serie, por lo que puedes cambiar el formato de resultado deseado modificando el orden de tus agrupaciones_por valores. Un ejemplo de agrupación que mostrará métricas separadas por ID de Tweet, tipo de métrica y que tiene el siguiente aspecto:

“agrupaciones”:{
“mi nombre de grupo”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


Agrupaciones que tienen 4group_byLos elementos solo son válidos si utilizan uno de los dos órdenes siguientes. Las solicitudes que tengan 4group_bylos elementos en un único grupo que no sean uno de los siguientes generarán un error. Además, solo se permite un único grupo con 4group_byelementos se permitirán por solicitud.

”grupo_por”: [
“Tweet.id”,
“engagement.type”,
“engagement.day”,
“interacción.hora”
]

“grupo_por”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“engagement.hour”
]
Límite de tamaño de PostSe pueden realizar solicitudes para un máximo de 25 id de Tweet a la vez.
Formato de la respuestaJSON. El encabezado de la solicitud debe especificar el formato JSON para la respuesta.
Límite de tasa de solicitudesSe te aplicarán límites de velocidad por minuto, según lo establecido en tu contrato y de acuerdo con tu nivel de acceso.
Solicitud de ejemplocurl -X POST”https://data-api.x.com/insights/engagement/28hr”
-H’Accept-Encoding: gzip’
-H’Autorización OAuth oauth_cliente_key=“consumer-key-para-la-App”,oauth_nonce=“nonce-generado”,oauth_firma=“firma-generada”,oauth_firma_método=“HMAC-SHA1”, OAuth_timestamp=“marca-de-tiempo-generada”,oauth_token=“token-de-acceso-para-usuario-autorizado”, OAuth_versión=“1.0”’
-d’{
“Tweet_ids”: [
“123456789”
],
“participación_tipos”: [
“impresiones”,
“interacciones”
],
“agrupaciones”:{
“serie-horaria-por-hora”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]
}
}
}‘
Ejemplo de respuesta{
“comenzar”:“2015-09-14T17:00:00Z”,
“final”:“2015-09-15T22:00:00Z”,
“serie-horaria-por-hora”:{
“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 disponiblesPara las consultas que incluyan IDs de Tweet que ya no estén disponibles (p. ej., porque fueron eliminados), se devolverán los datos correspondientes para todos los IDs de Tweet disponibles y se hará referencia a los IDs de Tweet no disponibles en una matriz llamadaunavailable_tweet_ids. Por ejemplo:

{
“comenzar”:“2015-11-17T22:00:00Z”,
“fin”:“2015-11-19T02:00:00Z”,
“no disponible_Tweet_ids”: [
“323456789”
],
“grupo1”:{
“423456789”:{
“favoritos”:“67”,
“respuestas”:“8”,
“retuits”: 26
}
}
}

​
POST /insights/engagement/historical

El endpoint histórico permite recuperar impresiones e interacciones para una colección de hasta 25 Tweets durante cualquier periodo de hasta 4 semanas. 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 peticiónPOST de HTTP
URLhttps://data-api.x.com/insights/engagement/historical
Tipo de contenidoapplication/json
CompresiónGzip. Para realizar una solicitud con compresión Gzip, envía un encabezado Accept-Encoding en la solicitud de conexión.
El encabezado debería tener el siguiente aspecto:

Accept-Encoding: gzip
Formato de PostLas solicitudes se pueden enviar como una solicitud POST cuyo cuerpo es un objeto JSON que contiene una colección de IDs de Tweet y una agrupación deseada. El POST se formatea como una matriz con untweets,interacciones, yagrupacionesobjeto. Cada solicitud puede incluir un máximo de 25 IDs de Tweet. Cada solicitud puede especificar una fecha de inicio y una fecha de fin personalizadas de hasta cuatro semanas de duración.


{
“Tweet_ids”: [
“ID de Tweet 1”,
“ID de Tweet 2”,
“ID de Tweet 3”
],
“participación_tipos”: [
“impresiones”,
“interacciones”,
“url_clics”,
“detalles_se expande”
],
“agrupaciones”:{
“nombre del grupo”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”,
“interacción.hora”
]
}
}
}
Fecha de inicio y de finSe pueden especificar fechas de inicio y fin personalizadas con lainicioyfinvalores 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 fechas de inicio y fin, la API, por defecto, tomará las 4 semanas inmediatamente anteriores.

El nivel de granularidad más bajo con el que la API de Engagement puede devolver data es por hora. Para cualquier solicitud realizada con valores de Start o End que no coincidan exactamente con un límite de hora, las solicitudes se ajustarán a la hora inclusiva más cercana. Por ejemplo, una solicitud con”comenzar”:“2015-07-01T12:24:00Z”y”fin”:“2015-07-10T08:37:00Z”de manera predeterminada será”inicio”:“2015-07-01T12:00:00Z”,“fin”:“2015-07-10T09:00:00Z”.
id de TweetUna matriz que incluye los IDs de los Tweet cuyos datos de interacción se consultarán. Tenga en cuenta que solo puede solicitar data para Tweets creados por el @handle autenticado. El endpoint histórico de 4 semanas admite hasta un máximo de 25 Tweets por solicitud y los IDs de los Tweet deben representarse como cadenas.
Tipos de interacciónUna matriz que incluye los tipos de métricas de interacción que se consultarán.

Para el endpoint histórico de 4 semanas,impresiones,interacciones, y todos los tipos de interacción individuales son métricas admitidas. Para ver la lista completa de métricas de interacción admitidas, consultaDatos de interacción.

Nota: Actualmente hay tres métricas que aparecerán como cero en las consultas realizadas antes del 15 de septiembre de 2015:favoritos,respuestas, yretuits.
AgrupacionesLos resultados de la Engagement API pueden devolverse en distintos grupos para ajustarse mejor a tus necesidades. Puedes incluir un máximo de 3 agrupaciones por solicitud.

Para cada agrupación, puede definir un nombre personalizado para facilitar la referencia a este tipo de agrupación en su aplicación. Una vez definido el nombre, puede elegir agrupar por uno o varios de los siguientes valores:
tweet.id
engagement.type
engagement.day
engagement.hour
Los agrupamientos se respetan en serie, por lo que puedes cambiar el formato de resultado deseado modificando el orden de tus grupos_por valores. Un ejemplo de agrupación que mostrará métricas separadas por ID de Tweet, tipo de métrica, y que se ve así:

“agrupaciones”:{
“mi nombre de grupo”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


Agrupaciones que tienen 4group_byLos elementos solo son válidos si usan uno de los dos órdenes siguientes. Las solicitudes que tengan 4group_bylos elementos en una única agrupación que no sean uno de los siguientes generarán un error. Además, solo se permitirá una única agrupación con 4group_bySe permitirán elementos por solicitud.

”grupo_por”: [
“tweet.id”,
“tipo_de_interacción”,
“engagement.day”,
“engagement.hour”
]

“grupo_por”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“interacción.hora”
]
Límite de tamaño de POSTSe pueden realizar solicitudes para un máximo de 25 id de Tweet a la vez.
Formato de la respuestaJSON. El encabezado de su solicitud debe especificar el formato JSON para la respuesta.
Límite de solicitudesSe te aplicarán límites de tasa por minuto, según lo especificado en tu contrato y de acuerdo con tu nivel de acceso.
Solicitud de ejemplocurl -XPOST”https://data-api.x.com/insights/engagement/historical”
-H’Accept-Encoding: gzip’
-H’Autorización OAuth oauth_cliente_key=“clave-de-consumidor-de-la-App”,oauth_nonce=“nonce-generada”,oauth_firma=“firma-generada”,oauth_firma_method=“HMAC-SHA1”, OAuth_marcaDeTiempo=“marca_de_tiempo_generada”,oauth_token=“token-de-acceso-para-usuario-autorizado”, OAuth_version=“1.0”’
-d’{
“comenzar”:“2015-08-01”,
“fin”:“2015-08-15”,
“Tweet_ids”: [
“123456789”,
“223456789”,
“323456789”
],
“engagement_Tipos”: [
“impresiones”,
“interacciones”,
“url_clics”,
“detalle_se expande”
],
“agrupaciones”:{
“tipos-por-Tweet-id”:{
“grupo_por”: [
“tweet.id”,
“engagement.type”
]
}
}
}‘
Ejemplo de respuesta{
“iniciar”:“2015-08-01T00:00:00Z”,
“final”:“2015-08-15T00:00:00Z”,
“tipos-por-id-de-Tweet”:{
“123456789”:{
“impresiones”:“0”,
“interacciones”:“0”,
“url_clics”:“0”,
“detalle_se expande”:“0”
},
“223456789”:{
“impresiones”:“788”,
“interacciones”:“134”,
“URL_clics”:“30”,
“detalle_se expande”:“1323”
},
“323456789”:{
“impresiones”:“4”,
“interacciones”:“0”,
“url_clics”:“2”,
“detalle_se expande”:“0”
}
}
}
id de Tweets no disponiblesPara las consultas que incluyan IDs de Tweet que ya no estén disponibles (p. ej., 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 mencionarán en una matriz llamadaunavailable_tweet_ids. Por ejemplo:

{
“comenzar”:“2015-11-17T22:00:00Z”,
“fin”:“2015-11-19T02:27:50Z”,
“no disponible_Tweet_ids”: [
“323456789”
],
“grupo1”:{
“423456789”:{
“Favoritos”:“67”,
“respuestas”:“8”,
“retweets”: 26
}
}
}

​
Códigos de respuesta

EstadoTextoDescripción
200OKLa solicitud se realizó correctamente.
400Bad RequestGeneralmente, esta respuesta se debe a JSON no válido en la solicitud o a que no se envió ningún cuerpo JSON.
401UnauthorizedLa autenticación HTTP falló por credenciales no válidas. Verifique sus claves y tokens de OAuth.
404Not FoundNo se encontró el recurso en la URL a la que se envió la solicitud, probablemente porque se usó una URL incorrecta.
429Too Many RequestsSu App excedió el límite de solicitudes a la API.
500Internal Server ErrorSe produjo un error en el lado de Gnip. Reintente la solicitud usando retroceso exponencial.
502Proxy ErrorSe produjo un error en el lado de Gnip. Reintente la solicitud usando retroceso exponencial.
503Service UnavailableSe produjo un error en el lado de Gnip. Reintente la solicitud usando retroceso exponencial.

​
Mensajes de error

En diversos escenarios, la Engagement API puede devolver mensajes de error específicos de la situación con los que su aplicación debe estar preparada para lidiar. La tabla a continuación incluye ejemplos comunes de estos mensajes y cómo debe interpretarlos. Tenga en cuenta que, en muchos casos, la Engagement API devolverá resultados parciales para los datos disponibles junto con mensajes de error específicos como parte de una respuesta 200 OK con más información.
Error MessageDescription
"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. Si no puede resolverlo, envíe 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 solicitó ya no están disponibles, lo que generalmente indica que se han eliminado o que ya no son públicos 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 solicitó específicamente para el endpoint /totals tienen más de 90 días 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 solicitó no están disponibles según el token de autenticación que está usando para recuperar datos en nombre de un tercero.