> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Engagement API
> Recupera métricas de impresiones e interacciones para Posts con la Engagement API enterprise usando los endpoints de totales, 28 horas y solicitudes históricas.
## Descripción general
[`Enterprise`](https://developer.x.com/en/products/x-api/enterprise)
*Esta es una API enterprise disponible únicamente dentro de nuestros niveles de acceso gestionado. Para usar esta API, primero debes configurar una cuenta con nuestro equipo de ventas enterprise. [Más información](/x-api/enterprise-gnip-2.0/enterprise-gnip)*
La Engagement API proporciona acceso a métricas de impresiones e interacciones de Posts. Si bien la mayoría de las métricas y endpoints requieren que te autentiques usando [OAuth 1.0a User Context](/resources/fundamentals/authentication), puedes acceder a las métricas públicas de Favorite, Retweet, Reply y Video Views usando [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#oauth-2-0) y el endpoint /totals.
**Nota:** Puedes observar diferencias entre los datos reportados en algunos de los paneles web de X y los datos reportados en la Engagement API. Estas diferencias ocurren porque los paneles web normalmente solo muestran las interacciones y/o impresiones que ocurrieron dentro del rango 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 caen fuera del espacio de ese mes, pero dentro del rango de tiempo solicitado. La Engagement API debe considerarse la fuente válida, en estos casos.
### Endpoints de solicitud
La Engagement API tiene tres endpoints:
#### Current Totals: \[/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: Impressions, Engagements, Favorites, Replies, Retweets, Quote Tweets y Video Views
* Admite la capacidad de recuperar métricas de **Impressions** y **Engagements** para Posts creados **en los últimos 90 días** usando OAuth 1.0a User Context
* Admite la capacidad de recuperar métricas de **Favorites, Retweets, Quote Tweets, Replies** y **Video Views** para **cualquier Post** usando 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 informes de un panel y para calcular tasas de engagement en una variedad de @handles
* Admite 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 individuales de interacción que hayan ocurrido 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 rastrear el rendimiento del contenido creado recientemente
* Admite todas las métricas disponibles
* Admite solicitar métricas para hasta 25 Posts por solicitud
#### Histórico: \[/historical]
* Las solicitudes pueden devolver impresiones, interacciones y un desglose de métricas individuales de interacción para el año más reciente, en función del momento de la interacción (no del momento de creación del Post).
* Las solicitudes admiten un parámetro de fecha de inicio y de fecha de fin, brindando flexibilidad para acotar a un período de tiempo específico de hasta 4 semanas de duración.
* Los datos de interacción de Posts se limitan a solo 365 días en el pasado.
* Los datos pueden agruparse por Post ID, y en series temporales de forma agregada, por día o por hora.
* Ideal para evaluar el rendimiento reciente contra un punto de referencia histórico o desarrollar una imagen histórica del rendimiento de un @handle.
* Admite todas las métricas disponibles.
* Admite 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 a través de la Engagement API.
Consulta nuestra [página de Interpretación de las métricas](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#interpreting-the-metrics) para saber más sobre las métricas siguientes.
| Métrica | Disponibilidad de endpoint | Se requiere User Context | Descripción |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------- | :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| impressions | Todos | Sí | Un conteo de cuántas veces se ha visto el Post. Esta métrica solo está disponible para Posts que se han publicado en los últimos 90 días. |
| engagements | Todos | Sí | Un conteo del número de veces que un usuario ha interactuado con el Post. Esta métrica solo está disponible para Posts que se han publicado en los últimos 90 días. |
| favorites | Todos | Sí - /28hrs y /Historical
No - /totals | Un conteo de cuántas veces el Post ha sido marcado como favorito. |
| retweets | Todos | Sí - /28hrs y /Historical
No - /totals | Un conteo de cuántas veces el Post ha sido Retweeteado. |
| quote\_tweets | /totals | No - /totals | Un conteo de las veces que un Post ha sido Retweeteado con un comentario (también conocido como Quote). |
| replies | Todos | Sí - /28hrs y /Historical
No - /totals | Un conteo de cuántas veces se ha respondido al Post. |
| video\_views | Todos | Sí - /28hrs y /Historical
No - /totals | Un conteo de cuántas veces un video en el Post dado ha sido visible al 50% durante al menos dos segundos.
Las vistas de video solo están disponibles para Posts que tienen 1800 días o menos. Si intentas solicitar vistas de video para cualquier Post más antiguo de 1800 días, recibirás el siguiente objeto dentro de 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:** Puedes ver una discrepancia entre la métrica de vistas de video mostrada en las plataformas propiedad y operadas por X (aplicación móvil y sitio web) y el número que recibes a través de los endpoints /28hr y /historical.
\* Las vistas de video mostradas en la interfaz de usuario de X y con el endpoint /totals mostrarán las vistas de video agregadas a través de todos los Posts en los que el video dado se ha publicado. Eso significa que la métrica mostrada en la UI incluye las vistas combinadas de cualquier instancia donde el video se haya Retweeteado o vuelto a publicar en Posts separados. Esta métrica no incluye las vistas de video en gifs.
\* Las vistas de video proporcionadas por los endpoints /28hr y /historical incluirán solo las vistas generadas por el Post específico para el que estás obteniendo métricas. Esta métrica no incluye las vistas de video en gifs. |
| media\_views | /28hr /historical | Sí | Un conteo de todas las vistas (autoplay y clic) de tu medio contadas entre videos, gifs e imágenes. |
| media\_engagements
([anteriormente Media Clicks](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#recent-changes-to-the-engagement-api)) | /28hr /historical | Sí | Un conteo de cuántas veces se ha hecho clic en un medio como una imagen o video en el Post. |
| url\_clicks | /28hr /historical | Sí | Un conteo de cuántas veces se ha hecho clic en una URL del Post. |
| hashtag\_clicks | /28hr /historical | Sí | Un conteo de cuántas veces se ha hecho clic en un hashtag del Post. |
| detail\_expands | /28hr /historical | Sí | Un conteo de cuántas veces se ha hecho clic en el Post para ver más detalles. |
| permalink\_clicks | /28hr /historical | Sí | Un conteo de cuántas veces se ha hecho clic en el permalink del Post (la página web individual dedicada a este Post). |
| app\_install\_attempts | /28hr /historical | Sí | Un conteo de cuántas veces se ha producido un evento App Install desde el Post |
| app\_opens | /28hr /historical | Sí | Un conteo de cuántas veces se ha producido un evento App Open desde el Post. |
| email\_tweet | /28hr /historical | Sí | Un conteo de cuántas veces se ha compartido el Post por correo electrónico. |
| user\_follows | /28hr /historical | Sí | Un conteo de cuántas veces se ha seguido al Usuario (autor del Post) desde este Post. |
| user\_profile\_clicks | /28hr /historical | Sí | Un conteo de cuántas veces se ha hecho clic en el perfil del Usuario (autor del Post) desde este Post. |
### Agrupaciones de engagement
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 `/28hr` y `/historical` pueden proporcionar métricas de series temporales y, por lo tanto, admiten:*
* engagement.day
* engagement.hour
Para saber más sobre agrupaciones, visita la página [Agrupaciones de la Engagement API](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings) dentro de la sección Guías.
## Guías
### Guía de inicio para desarrolladores
#### Introducción
El propósito de esta documentación es proporcionar a los desarrolladores una introducción a la integración con la Engagement API. Comenzaremos discutiendo los "porqués" de la integración y luego profundizaremos en los detalles técnicos del "cómo".
##### **¿Qué proporciona la Engagement API?**
* La Engagement API proporciona datos de impresiones e interacción para los Posts propios de cualquier cuenta de X de los últimos 90 días, suponiendo que dicha cuenta haya autorizado a tu App a solicitar métricas en su nombre usando [OAuth de 3 pasos](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). Esta solución potente, pero fácil de implementar, brinda acceso inmediato a impresiones e interacciones profundas como clics en URL, clics en #hashtags y muchos más.
* La Engagement API proporciona métricas agregadas totales de favorites, Retweets, Quote Tweets, replies y vistas de video para cualquier Post. Esto se puede utilizar como una forma potente de obtener datos básicos de engagement sobre cualquier Post o colección de Posts.
* La Engagement API entrega nuevo valor a las plataformas de social listening, marketing y publicación al permitir que los clientes midan el ROI en X midiendo eficazmente el rendimiento del contenido usando 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 Posts, métricas deseadas y un rango de tiempo, para el que la API devuelve datos al instante.
##### **¿Por qué integrar? Ejemplos de casos de uso**
* Comprende el alcance total de tu 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.
* Genera métricas de engagement totales y en series temporales.
* Comprende métricas básicas de engagement (favorites, Retweets, Quote Tweets, replies) sobre cualquier Post público.
* Usa estas métricas para determinar qué tipos de Posts funcionan, para poder publicarlos con más frecuencia y obtener más impresiones y más interacciones para mi contenido.
* Automatiza el comportamiento de marketing (como Retweetear contenido de una cuenta propia diferente) cada vez que uno de mis Posts alcance 100 Likes u otro umbral.
* Compara y analiza mis campañas entre sí como una herramienta para pruebas A/B.
* Analiza qué tipo de contenido resuena para que mi departamento de atención al cliente determine cómo y cuándo responder.
* Muestra analíticas para el contenido que se publica desde mi plataforma.
La [Engagement API se lanzó en 2016](https://blog.x.com/official/en_us/a/2016/gnip-s-engagement-api-is-now-generally-available.html) y fue la primera X API en proporcionar estas métricas de engagement en profundidad a escala. La Engagement API es fácil de usar y permite a los clientes automatizar el proceso. Aquí hay un caso práctico que describe una integración de ejemplo:
* [Midiendo el éxito de campañas con la Cruz Roja](https://blog.x.com/developer/en_us/topics/spotlight/2016/measuring-campaign-success-with-the-red-cross.html)[](https://simplymeasured.com/blog/true-twitter-impressions-and-url-clicks-new-from-simply-measured/#sm.0007werel134td8zqf02m2mduumr6)
Ahora que hemos explorado los "porqués" de la Engagement API, comencemos a profundizar en los detalles técnicos.
#### Integración de la Engagement API
##### **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 engagement codificadas en JSON. Las solicitudes constan de tres partes principales (sigue los enlaces para más documentación):
* Array de ***Post IDs***.
* Array especificando los [tipos de métricas](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview).