diff --git a/es/x-ads-api/analytics.mdx b/es/x-ads-api/analytics.mdx
new file mode 100644
index 000000000..09e71e3ce
--- /dev/null
+++ b/es/x-ads-api/analytics.mdx
@@ -0,0 +1,1263 @@
+---
+title: "Analytics"
+keywords: ["analítica de publicidad", "analítica de anuncios", "analítica de campañas", "métricas de anuncios", "métricas de publicidad", "rendimiento de campañas"]
+description: "Obtén métricas de rendimiento de campañas en la X Ads API utilizando endpoints de analytics síncronos y asíncronos con opciones de segmentación y granularidad."
+---
+
+Las métricas de analytics ayudan a partners y anunciantes a comprender el rendimiento del contenido que promocionan en X. Esto incluye información como impresiones, clics, vistas de video y gasto. Además, los partners y anunciantes pueden obtener métricas detalladas para distintos segmentos de las audiencias a las que llegan.
+
+La Ads API admite dos formas de obtener métricas detalladas de rendimiento de campañas: de manera síncrona y asíncrona. Con las llamadas síncronas de analytics, las métricas solicitadas se devuelven en la respuesta. Con los endpoints asíncronos de analytics, las métricas solicitadas están disponibles en un archivo de resultados descargable una vez que el "job" asociado haya terminado de procesarse. El endpoint síncrono admite rangos de tiempo cortos y es ideal para optimizaciones de campaña en tiempo real. Los endpoints asíncronos admiten rangos de tiempo mucho más largos y, por tanto, están pensados para obtener muchos más datos, siendo ideales para generar reportes o realizar recargas históricas (backfills).
+
+## Detalles
+
+### Síncrono vs. asíncrono
+
+Las diferencias entre los endpoints de analytics síncronos y asíncronos se resumen en la siguiente tabla. Esta información está pensada para ayudar a los desarrolladores a elegir qué conjunto de endpoints utilizar.
+
+| Característica | Síncrono | Asíncrono |
+| :-- | :-- | :-- |
+| Límite de uso | A nivel de usuario: 250 solicitudes / 15 minutos | A nivel de cuenta: 100 jobs concurrentes\* |
+| Rango de tiempo | 7 días | 90 días (no segmentado) 45 días (segmentado) |
+| Segmentación | No | Sí |
+| La respuesta devuelve | Datos de métricas | Estado de procesamiento del job\*\* |
+| Caso de uso recomendado | Optimización en tiempo real Solicitudes de interfaz de usuario | Sincronización programada periódicamente Recarga (backfill) de datos históricos |
+
+
+ \* Se refiere al número máximo de jobs que pueden estar en estado de procesamiento en un momento dado.
+
+ \*\* Una vez que el job haya terminado de procesarse correctamente, se devuelve una URL. Desde allí se puede descargar el archivo de resultados comprimido (gzip).
+
+ Más allá de esto, los endpoints ofrecen la misma funcionalidad.
+
+
+### Casos de uso
+
+Existen tres casos de uso principales para analytics.
+
+1. Optimización en tiempo real: usar métricas de rendimiento para actualizar campañas activas
+2. Sincronización: sincronizaciones en segundo plano programadas periódicamente
+3. Onboarding de cuentas nuevas: recarga (backfill) de datos históricos
+
+El endpoint síncrono de analytics puede utilizarse para optimización en tiempo real, con el fin de actualizar campañas en función de los cambios en las métricas durante los últimos 5 a 15 minutos. Cualquiera de los endpoints puede emplearse para sincronización de analytics. Ten en cuenta que el rango de tiempo deseado y la necesidad de segmentación determinarán qué endpoint utilizar. El onboarding de cuentas nuevas solo debe realizarse con los endpoints asíncronos de analytics. (El endpoint síncrono de analytics nunca debe usarse para obtener grandes volúmenes de datos).
+
+Los endpoints asíncronos de analytics pueden alimentar dashboards y otros elementos de interfaz de usuario si las métricas se sincronizan con un proceso de backend. Tu implementación debe evitar llamar a los endpoints asíncronos de analytics para responder a solicitudes de la interfaz de usuario.
+
+### Opciones de la solicitud
+
+Las solicitudes de analytics están acotadas a cuentas de anuncios y, por tanto, requieren el ID de la cuenta en la ruta del recurso. Las opciones de la solicitud, listadas a continuación, se especifican como parámetros de consulta. Se requieren los siguientes tipos de valores.
+
+- Entidades: el tipo de entidad y hasta 20 IDs de entidad para los que deseas solicitar analytics
+- Rango de tiempo: las horas de inicio y fin, expresadas en ISO 8601
+ - **Nota:** deben expresarse en horas completas
+- Grupos de métricas: uno o más conjuntos de métricas relacionadas (consulta Metrics and Segmentation para ver la lista de métricas dentro de cada grupo)
+- Granularidad: especifica el nivel de agregación con el que se deben devolver las métricas
+- Placement: determina si las métricas se obtienen para anuncios servidos dentro o fuera de X
+ - **Nota:** solo se puede especificar un único valor de placement por solicitud
+
+Usa los parámetros de solicitud `start_time` y `end_time` para especificar un rango de tiempo. Estos valores deben alinearse con la granularidad especificada de la siguiente manera.
+
+1. `TOTAL`: especifica cualquier rango de tiempo (dentro de los límites del endpoint)
+2. `DAY`: tanto el valor de inicio como el de fin deben alinearse con la medianoche en la zona horaria de la cuenta
+3. `HOUR`: especifica cualquier rango de tiempo (dentro de los límites del endpoint)
+
+La hora de fin es exclusiva. Por ejemplo, una solicitud con `start_time=2026-01-01T00:00:00Z` y `end_time=2026-01-02T00:00:00Z` devolverá métricas de analytics correspondientes a un solo día (no dos), ya que este rango de tiempo cubre únicamente un período de 24 horas.
+
+**Segmentación**
+
+Disponible únicamente a través de nuestros endpoints asíncronos de analytics, la segmentación permite a partners y anunciantes obtener métricas desglosadas por determinados valores de segmentación. Para solicitar métricas segmentadas, utiliza el parámetro de solicitud `segmentation_type`. Para más detalles sobre las opciones de segmentación, consulta [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation).
+
+## Preguntas frecuentes
+
+¿Por qué los números de la Ads API no coinciden con lo que se muestra en la interfaz de X Ads?
+
+- Asegúrate de haber solicitado los datos para todos los placements: `ALL_ON_TWITTER`, `SPOTLIGHT` y `TREND`.
+- Recuerda que las horas de fin en la Ads API son exclusivas; en la interfaz de Ads son inclusivas
+
+¿Por qué los números cambian dependiendo de cuándo solicito los datos?
+
+- En cuanto las métricas de reporte están disponibles, puedes obtenerlas. Están disponibles casi en tiempo real. Sin embargo, estos resultados iniciales son estimaciones y, por tanto, se espera que cambien. Las métricas se finalizan después de 24 horas, salvo los datos de gasto.
+- Las métricas de gasto suelen ser definitivas dentro de los 3 días siguientes al evento. No obstante, procesamos los datos de facturación hasta 14 días desde la fecha del evento (por filtrado de spam, por ejemplo).
+
+¿Cómo puedo determinar qué IDs de entidad solicitar para un período de tiempo específico?
+
+- Usa el [endpoint Active Entities](/x-ads-api/analytics#active-entities-2)
+
+¿Por qué todos los valores en la respuesta de analytics son `null`?
+
+- Es probable que la campaña no se haya servido durante el período de tiempo solicitado
+- Usa el [endpoint Active Entities](/x-ads-api/analytics#active-entities-2) para determinar qué entidades consultar para analytics y en qué período de tiempo
+
+¿Por qué la API muestra valores `null` mientras que la UI muestra 0?
+
+- La UI elige mostrar estos valores como 0, pero los valores son equivalentes
+
+¿Cómo puedo solicitar métricas asociadas con un placement granular, como la timeline de X?
+
+- Admitimos los siguientes valores de placement en analytics: `ALL_ON_TWITTER`, `SPOTLIGHT` y `TREND`
+
+¿Es posible obtener métricas para entidades eliminadas o pausadas?
+
+- Sí. El estado de la entidad no afecta la disponibilidad de las métricas de analytics.
+
+¿Por qué los valores segmentados no coinciden con los no segmentados?
+
+- _No_ se espera que los datos segmentados sumen al 100 % de los datos no segmentados, debido a cómo se deriva esta información.
+
+¿Por qué los valores segmentados de la API no coinciden con lo que muestra la UI de Ads Manager?
+
+- La API devuelve métricas segmentadas acotadas al tipo de entidad específico que consultas (CAMPAIGN, PROMOTED\_TWEET). La UI de Ads Manager agrega los datos entre tipos de entidades. Son vistas diferentes de los mismos datos subyacentes y este es el comportamiento esperado.
+
+¿Es posible solicitar datos segmentados por múltiples dimensiones?
+
+- No admitimos la segmentación múltiple.
+
+## Buenas prácticas
+
+Algunas buenas prácticas al recopilar datos de [analytics](/x-ads-api/analytics) de la Ads API.
+
+### Rate Limiting y reintentos
+
+- En consultas que están limitadas por rate limit (las que devuelven un código de estado `HTTP 429`), debes inspeccionar el header `x-rate-limit-reset` y reintentar solo en o después del momento indicado.
+- En consultas que resulten en un código de estado HTTP 503 Service Unavailable, debes inspeccionar el header `retry-after` y reintentar solo después del momento indicado.
+- Las aplicaciones que no respeten los tiempos indicados para los reintentos podrían ver su acceso a la Ads API revocado o limitado sin previo aviso.
+
+### Métricas de analytics en pocas palabras
+
+- Todas las métricas de analytics quedan fijas y no cambiarán después de 24 horas, salvo `billed_charge_local_micro`.
+- La métrica `billed_charge_local_micro` es una estimación hasta 3 días después de que se devuelven los datos.
+- Tras 24 horas, esta métrica puede disminuir debido a créditos por sobregasto (anuncios servidos después del `end_time` indicado) y por eventos facturables que se determinen como junk. Esta métrica cambia mínimamente después de 24 horas.
+- Consulta [Analytics](/x-ads-api/analytics) para más información.
+
+### Obtención de datos no segmentados en tiempo real
+
+- Proporciona siempre tanto un `start_time` como un `end_time`.
+- No extraigas datos para ninguna entidad con más de 7 días de antigüedad.
+- Solicita los datos (idealmente) con granularidad `HOUR`, ya que siempre puedes agregar y sumar métricas para obtener granularidades `DAY` y `TOTAL`.
+- Solicita los datos (idealmente) a nivel de `line_items` y `promoted_tweets`, ya que siempre puedes agregar y sumar estas métricas para obtener totales en toda la jerarquía de entidades de anuncios (es decir, a nivel de campaña, instrumento de financiación o cuenta).
+- Guarda y almacena los valores de las métricas de analytics de tu lado (localmente).
+- No consultes repetidamente datos con más de 30 días de antigüedad. Estos datos no cambiarán y deben almacenarse localmente.
+- Todos los datos no segmentados son en tiempo real y deberían estar disponibles a los pocos segundos de ocurrir un evento.
+- Agrupa las métricas de conversión y las que no son de conversión en solicitudes separadas.
+
+### Obtención de datos segmentados
+
+- Consulta las directrices proporcionadas anteriormente en "Obtención de datos no segmentados en tiempo real". A continuación se ofrecen recomendaciones adicionales.
+- Para la mayoría de los tipos de datos segmentados, es posible que los datos no estén completos durante hasta 1 hora en ocasiones. Los datos segmentados por `INTERESTS` pueden retrasarse hasta 12 horas.
+- No se espera que los datos segmentados sumen al 100 % de los datos no segmentados, debido a cómo se deriva esta información.
+
+### Obtención de datos históricos
+
+- Al realizar backfill de datos (es decir, al añadir una nueva cuenta de anunciante), es posible que tengas que hacer varias solicitudes en bloques más pequeños de `start_time` y `end_time`.
+- Limita tus extracciones a ventanas de fechas de 30 días.
+- Regula (throttle) estas solicitudes y distribúyelas en el tiempo para no agotar tus rate limits con estas extracciones.
+
+### Ejemplo
+
+Puedes encontrar un script de ejemplo que demuestra algunas de estas buenas prácticas (`fetch_stats`) en nuestro repositorio de [ads-platform-tools en GitHub](https://github.com/xdevplatform/ads-platform-tools).
+
+## Métricas por objetivo
+
+Las métricas aplicables a una entidad dependen del [objetivo de la campaña](/x-ads-api/campaign-management). Usa esta guía para determinar los grupos de métricas relevantes que debes obtener para cada tipo de objetivo, así como la forma de calcular métricas derivadas adicionales.
+
+### `ENGAGEMENTS`
+
+**Grupos de métricas relevantes:** `ENGAGEMENT` y `BILLING`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| Engagement Rate | `engagements/impressions` |
+| CPE | `billed_charge_local_micro/engagements` |
+
+### `WEBSITE_CLICKS` y `WEBSITE_CONVERSIONS`
+
+**Grupos de métricas relevantes:** `ENGAGEMENT`, `BILLING` y `WEB_CONVERSION`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Click Rate | `clicks/impressions` |
+| CPLC | `billed_charge_local_micro/clicks` |
+| Total Conversions | `conversion_custom` \+ `conversion_site_visits` \+ `conversion_sign_ups` \+ `conversion_downloads` \+ `conversion_purchases` |
+| Conversion Rate | Total Conversions / `impressions` |
+| CPA | `billed_charge_local_micro` / Total Conversions |
+
+### `APP_INSTALLS`
+
+**Grupos de métricas relevantes:** `ENGAGEMENT`, `BILLING`, `MOBILE_CONVERSION` y `LIFE_TIME_VALUE_MOBILE_CONVERSION`. `VIDEO` también es aplicable si se utiliza una video app card en los creativos.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| App Click Rate | `app_clicks/impressions` |
+| CPAC | `billed_charge_local_micro/app_clicks` |
+| CPI | `billed_charge_local_micro/mobile_conversion_installs` |
+
+### `FOLLOWERS`
+
+**Grupos de métricas relevantes:** `ENGAGEMENT` y `BILLING`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Follow Rate | `follows/impressions` |
+| CPF | `billed_charge_local_micro/follows` |
+
+### `VIDEO_VIEWS`
+
+**Grupos de métricas relevantes:** `ENGAGEMENT`, `BILLING` y `VIDEO`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Video Rate | `video_total_views/impressions` |
+| Cost Per View | `billed_charge_local_micro/video_total_views` |
+
+### `VIDEO_VIEWS_PREROLL`
+
+**Grupos de métricas relevantes:** `ENGAGEMENT`, `BILLING` y `VIDEO`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Video Rate | `video_total_views/impressions` |
+| Cost Per View | `billed_charge_local_micro/video_total_views` |
+
+## Métricas y segmentación
+
+Este documento es una visión general de las métricas disponibles desde nuestro [Analytics](/x-ads-api/analytics) para cada tipo de entidad, así como la segmentación disponible para cada métrica.
+
+| | | | | | | |
+| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
+| | Grupos de métricas | | | | | |
+| Entidad | [`ENGAGEMENT`](#engagement) | [`BILLING`](#BILLING) | [`VIDEO`](#VIDEO) | [`WEB_CONVERSION`](#WEB_CONVERSION) | [`MOBILE_CONVERSION`](#MOBILE_CONVERSION) | [`LIFE_TIME_VALUE_MOBILE_CONVERSION`](#LIFE_TIME_VALUE_MOBILE_CONVERSION) |
+| `ACCOUNT` | ✔\* | | | | | |
+| `FUNDING_INSTRUMENT` | ✔\* | ✔ | | | | |
+| `CAMPAIGN` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| `LINE_ITEM` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| `PROMOTED_TWEET` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+
+\*Algunas métricas de la familia `ENGAGEMENT` no están disponibles a nivel de cuenta ni de instrumento de financiación. Consulta la sección `ENGAGEMENT` para más detalles.
+
+### Métricas disponibles por grupo de métricas
+
+#### `ENGAGEMENT`
+
+| | | | | |
+| :-- | :-- | :-- | :-- | :-- |
+| Métrica | Descripción | Segmentación disponible | Tipo de dato | Disponible para Account / Funding Instrument |
+| `engagements` | Número total de engagements | ✔ | Array de ints | ✔ |
+| `impressions` | Número total de impresiones | ✔ | Array de ints | ✔ |
+| `retweets` | Número total de reposts | ✔ | Array de ints | ✔ |
+| `replies` | Número total de respuestas | ✔ | Array de ints | ✔ |
+| `likes` | Número total de likes | ✔ | Array de ints | ✔ |
+| `follows` | Número total de follows | ✔ | Array de ints | ✔ |
+| `card_engagements` | Número total de engagements de card | ✔ | Array de ints | |
+| `clicks` | Número total de clics, incluyendo favoritos y otros engagements | ✔ | Array de ints | |
+| `app_clicks` | Número de intentos de instalación o apertura de la app | ✔ | Array de ints | |
+| url\_clicks | Total de clics en el enlace o la Website Card de un anuncio, incluyendo los orgánicos. | ✔ | Array de ints | |
+| `qualified_impressions` | Número total de impresiones cualificadas | ✔ | Array de ints | |
+| `carousel_swipes` | Total de swipes en imágenes o videos de Carrusel | ✔ | Array de ints | |
+
+#### `BILLING`
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descripción | Segmentación disponible | Tipo de dato |
+| `billed_engagements` | Número total de engagements facturados | ✔ | Array de ints |
+| `billed_charge_local_micro` | Gasto total en micros | ✔ | Array de ints |
+
+#### `VIDEO`
+
+Aviso sobre cambios en la definición de métricas de video:
+
+La métrica `video_total_views` dentro del grupo de métricas `VIDEO` reportará cualquier vista que esté visible al menos al 50 % durante 2 segundos, según el estándar MRC.
+
+Nuestra definición original de vista de video del 100 % visible durante al menos 3 segundos seguirá estando disponible como una nueva métrica `video_3s100pct_views` dentro del grupo de métricas `VIDEO`. Para continuar pujando y cobrando con base en la definición original de vista, usa la nueva bid\_unit `VIEW_3S_100PCT` disponible.
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descripción | Segmentación disponible | Tipo de dato |
+| `video_total_views` | Número total de vistas de video | ✔ | Array de ints |
+| `video_views_25` | Número total de vistas en las que se reprodujo al menos el 25 % del video. | ✔ | Array de ints |
+| `video_views_50` | Número total de vistas en las que se reprodujo al menos el 50 % del video. | ✔ | Array de ints |
+| `video_views_75` | Número total de vistas en las que se reprodujo al menos el 75 % del video. | ✔ | Array de ints |
+| `video_views_100` | Número total de vistas en las que se reprodujo el 100 % del video. | ✔ | Array de ints |
+| `video_cta_clicks` | Total de clics en la llamada a la acción | ✔ | Array de ints |
+| `video_content_starts` | Número total de inicios de reproducción de video | ✔ | Array de ints |
+| `video_3s100pct_views` | Número total de vistas en las que se reprodujeron al menos 3 segundos estando el 100 % en pantalla (legacy `video_total_views`) | ✔ | Array de ints |
+| `video_6s_views` | Número total de vistas en las que se reprodujeron al menos 6 segundos del video | ✔ | Array de ints |
+| `video_15s_views` | Número total de vistas en las que se reprodujeron al menos 15 segundos del video o el 95 % de la duración total | ✔ | Array de ints |
+
+#### `WEB_CONVERSION`
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descripción | Segmentación disponible | Tipo de dato |
+| `conversion_purchases` | Número de conversiones del tipo PURCHASE y el correspondiente importe de venta y cantidad de pedido | Solo `PLATFORMS` | Objeto JSON |
+| `conversion_sign_ups` | Número de conversiones del tipo SIGN\_UP y el correspondiente importe de venta y cantidad de pedido | Solo `PLATFORMS` | Objeto JSON |
+| `conversion_site_visits` | Número de conversiones del tipo SITE\_VISIT y el correspondiente importe de venta y cantidad de pedido | Solo `PLATFORMS` | Objeto JSON |
+| `conversion_downloads` | Número de conversiones del tipo DOWNLOAD y el correspondiente importe de venta y cantidad de pedido | Solo `PLATFORMS` | Objeto JSON |
+| `conversion_custom` | Número de conversiones del tipo CUSTOM y el correspondiente importe de venta y cantidad de pedido | Solo `PLATFORMS` | Objeto JSON |
+
+#### `MOBILE_CONVERSION`
+
+Las estadísticas de conversión móvil solo están disponibles para las cuentas de anunciante habilitadas para MACT.
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descripción | Segmentación disponible | Tipo de dato |
+| `mobile_conversion_spent_credits` | Desglose de conversiones móviles del tipo SPENT\_CREDIT por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_installs` | Desglose de conversiones móviles del tipo INSTALL por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_content_views` | Desglose de conversiones móviles del tipo CONTENT\_VIEW por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_add_to_wishlists` | Desglose de conversiones móviles del tipo ADD\_TO\_WISHLIST por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_checkouts_initiated` | Desglose de conversiones móviles del tipo CHECKOUT\_INITIATED por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_reservations` | Desglose de conversiones móviles del tipo RESERVATION por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_tutorials_completed` | Desglose de conversiones móviles del tipo TUTORIAL\_COMPLETED por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_achievements_unlocked` | Desglose de conversiones móviles del tipo ACHIEVEMENT\_UNLOCKED por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_searches` | Desglose de conversiones móviles del tipo SEARCH por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_add_to_carts` | Desglose de conversiones móviles del tipo ADD\_TO\_CART por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_payment_info_additions` | Desglose de conversiones móviles del tipo PAYMENT\_INFO\_ADDITION por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_re_engages` | Desglose de conversiones móviles del tipo RE\_ENGAGE por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_shares` | Desglose de conversiones móviles del tipo SHARE por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_rates` | Desglose de conversiones móviles del tipo RATE por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_logins` | Desglose de conversiones móviles del tipo LOGIN por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_updates` | Desglose de conversiones móviles del tipo UPDATE por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_levels_achieved` | Desglose de conversiones móviles del tipo LEVEL\_ACHIEVED por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_invites` | Desglose de conversiones móviles del tipo INVITE por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_key_page_views` | Desglose de conversiones móviles del tipo KEY\_PAGE\_VIEW por post\_view y post\_engagement | ✔ | Objeto JSON |
+| mobile\_conversion\_downloads | Desglose de conversiones móviles del tipo DOWNLOAD por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| mobile\_conversion\_purchases | Desglose de conversiones móviles del tipo PURCHASE por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| mobile\_conversion\_sign\_ups | Desglose de conversiones móviles del tipo SIGN\_UP por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+| mobile\_conversion\_site\_visits | Desglose de conversiones móviles del tipo SITE\_VISIT por post\_view, post\_engagement, assisted, order\_quantity y sale\_amount | ✔ | Objeto JSON |
+
+#### `LIFE_TIME_VALUE_MOBILE_CONVERSION`
+
+Las estadísticas de conversión móvil de por vida (lifetime) solo están disponibles para las cuentas de anunciante habilitadas para MACT.
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descripción | Segmentación disponible | Tipo de dato |
+| `mobile_conversion_lifetime_value_purchases` | Desglose de conversiones móviles del tipo PURCHASE | | Objeto JSON |
+| `mobile_conversion_lifetime_value_sign_ups` | Desglose de conversiones móviles del tipo SIGN\_UP | | Objeto JSON |
+| `mobile_conversion_lifetime_value_updates` | Desglose de conversiones móviles del tipo UPDATE | | Objeto JSON |
+| `mobile_conversion_lifetime_value_tutorials_completed` | Desglose de conversiones móviles del tipo TUTORIAL\_COMPLETED | | Objeto JSON |
+| `mobile_conversion_lifetime_value_reservations` | Desglose de conversiones móviles del tipo RESERVATION | | Objeto JSON |
+| `mobile_conversion_lifetime_value_add_to_carts` | Desglose de conversiones móviles del tipo ADD\_TO\_CART | | Objeto JSON |
+| `mobile_conversion_lifetime_value_add_to_wishlists` | Desglose de conversiones móviles del tipo ADD\_TO\_WISHLIST | | Objeto JSON |
+| `mobile_conversion_lifetime_value_checkouts_initiated` | Desglose de conversiones móviles del tipo CHECKOUT\_INITIATED | | Objeto JSON |
+| `mobile_conversion_lifetime_value_levels_achieved` | Desglose de conversiones móviles del tipo LEVEL\_ACHIEVED | | Objeto JSON |
+| `mobile_conversion_lifetime_value_achievements_unlocked` | Desglose de conversiones móviles del tipo ACHIEVEMENT\_UNLOCKED | | Objeto JSON |
+| `mobile_conversion_lifetime_value_shares` | Desglose de conversiones móviles del tipo SHARE | | Objeto JSON |
+| `mobile_conversion_lifetime_value_invites` | Desglose de conversiones móviles del tipo INVITE | | Objeto JSON |
+| `mobile_conversion_lifetime_value_payment_info_additions` | Desglose de conversiones móviles del tipo PAYMENT\_INFO\_ADDITION | | Objeto JSON |
+| `mobile_conversion_lifetime_value_spent_credits` | Desglose de conversiones móviles del tipo SPENT\_CREDIT | | Objeto JSON |
+| `mobile_conversion_lifetime_value_rates` | Desglose de conversiones móviles del tipo RATE | | Objeto JSON |
+
+### Segmentación
+
+La elaboración de reportes con segmentación permite obtener métricas desglosadas por los valores de un tipo de segmentación determinado. La segmentación solo está disponible a través de [consultas asíncronas de analytics](/x-ads-api/analytics#asynchronous-analytics) debido a su considerable complejidad añadida.
+
+A partir de mayo de 2026, solo están habilitados los siguientes tipos de segmentación. METROS devuelve códigos DMA de Nielsen como cadenas numéricas (819 = Seattle-Tacoma). Los tipos de segmentación geográfica como METROS requieren el parámetro country (96683cc9126741d1 para US).
+
+| | |
+| :-- | :-- |
+| Tipo de segmentación | Parámetro `country` requerido |
+| `AGE` | |
+| `GENDER` | |
+| `METROS` | ✔ |
+| `PLATFORMS` | |
+
+## Métricas derivadas
+
+Las métricas de campaña dependen de su [objetivo de campaña](/x-ads-api/campaign-management). Usa esta guía para determinar cómo calcular métricas derivadas para utilizarlas en función de los objetivos establecidos.
+
+Cualquier `metric` sin llaves es una métrica que devuelven los endpoints de [analytics](/x-ads-api/analytics#synchronous-analytics) de la Ads API. Cualquier nombre rodeado por `{llaves}` indica una métrica derivada para esa categoría.
+
+### ENGAGEMENTS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `{Total Engagements}` | `promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements` o `promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows` |
+| `{Engagement Rate}` | `{Total Engagements} / {Impressions}` |
+| `billed_charge_local_micro / {Total Engagements}` | |
+
+### WEBSITE\_CLICKS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `{Link Clicks}` | `promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks` |
+| `{Click Rate}` | `{Link Clicks} / {Impressions}` |
+| `billed_charge_local_micro / {Link Clicks}` | |
+| `conversion_site_visits` | |
+| `{Conversion Rate}` | `conversion_site_visits / {Impressions}` |
+| `billed_charge_local_micro / conversion_site_visits` | |
+
+### APP\_INSTALLS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `{App Clicks}` | `promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks` |
+| `{App Click Rate}` | `{App Clicks} / {Impressions}` |
+| `billed_charge_local_micro / {App Clicks}` | |
+| `billed_charge_local_micro / mobile_conversion_installs` | |
+
+### FOLLOWERS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| `promoted_account_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `promoted_account_follows` | |
+| `{Follow Rate}` | `promoted_account_follow_rate` |
+| `billed_charge_local_micro / promoted_account_follows` | |
+
+### VIDEO\_VIEWS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| | `billed_charge_local_micro / {Impressions} / 1000` |
+| `{Video Views}` | `promoted_video_total_views` |
+| `{Video Rate}` | `promoted_video_total_views / {Impressions}` |
+| `{Cost Per View}` | `billed_charge_local_micro / promoted_video_total_views` |
+
+### QUALIFIED\_IMPRESSIONS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo con la métrica expuesta |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| | `billed_charge_local_micro / {Impressions} / 1000` |
+| `{Qualified Impressions}` | `promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions` |
+| `{Qualified Impression Rate}` | `{Qualified Impressions} / {Impressions}` |
+| `{Cost Per 1000 Qualified Impressions }` | `billed_charge_local_micro / {Qualified Impressions} / 1000` |
+
+### CUSTOM
+
+Para `placement_type` `PROMOTED_ACCOUNT`, consulta el objetivo `FOLLOWERS` indicado anteriormente. Para todos los demás placements con este objetivo, consulta `ENGAGEMENTS` para las métricas derivadas correspondientes.
+
+## Guías
+
+### Active Entities
+
+#### Introducción
+
+El [endpoint Active Entities](/x-ads-api/analytics#get-stats-accounts-account-id-active-entities) está pensado para usarse junto con nuestros endpoints de analytics [síncronos](/x-ads-api/analytics#get-stats-accounts-account-id) y [asíncronos](/x-ads-api/analytics#asynchronous-analytics), ya que proporciona información sobre qué campañas solicitar para analytics. Lo hace devolviendo detalles sobre las entidades de anuncios y cuándo cambiaron sus métricas. Usar este endpoint simplificará enormemente tu código y la lógica de obtención de analytics.
+
+Esta guía incluye información y contexto sobre el endpoint y su fuente de datos. También proporciona [directrices de uso](#usage) y una serie de [solicitudes de ejemplo](#example) que muestran cómo usar Active Entities junto con nuestros endpoints de analytics. La [sección Resumen](#summary) ofrece una descripción de alto nivel del enfoque recomendado.
+
+#### Datos
+
+Cada vez que cambia la métrica de una entidad de anuncios, registramos información sobre ese cambio. Estos eventos de cambio se almacenan en buckets horarios e incluyen detalles sobre la entidad y el momento al que aplica el cambio. Esto último es necesario porque los eventos de cambio no siempre corresponden al momento en que fueron registrados. Los ajustes de facturación son una razón habitual para esto, pero hay otras.
+
+#### Endpoint
+
+### Solicitud
+
+Las solicitudes de Active Entities están acotadas a cuentas de anuncios y tienen tres parámetros de consulta obligatorios: `entity`, `start_time` y `end_time`.
+
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2026-03-05T00:00:00Z&end_time=2026-03-06T00:00:00Z"`
+
+Se admiten los siguientes valores de `entity`: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT` y `PROMOTED_TWEET`. Esto refleja los tipos de entidad que admiten nuestros endpoints de analytics.
+
+Los valores `start_time` y `end_time` deben expresarse en [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) y especifican qué buckets horarios consultar. Deben expresarse en horas completas.
+
+Este endpoint también admite tres parámetros opcionales que pueden usarse para filtrar los resultados: `funding_instrument_ids`, `campaign_ids` y `line_item_ids`. Funcionan en todos los niveles de la jerarquía de anuncios y con cualquier tipo de `entity` especificado.
+
+### Respuesta
+
+La respuesta de Active Entities para la solicitud anterior se muestra a continuación.
+
+```json
+ {
+ "request": {
+ "params": {
+ "account_id": "18ce54d4x5t",
+ "entity": "PROMOTED_TWEET",
+ "start_time": "2026-03-05T00:00:00Z",
+ "end_time": "2026-03-06T00:00:00Z"
+ }
+ },
+ "data": [
+ {
+ "entity_id": "2r0wxw",
+ "activity_start_time": "2026-03-04T20:55:20Z",
+ "activity_end_time": "2026-03-05T03:43:56Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ },
+ {
+ "entity_id": "2r30fn",
+ "activity_start_time": "2026-03-05T08:11:08Z",
+ "activity_end_time": "2026-03-05T14:40:59Z",
+ "placements": [
+ "ALL_ON_TWITTER",
+ "PUBLISHER_NETWORK"
+ ]
+ }
+ ]
+ }
+```
+
+El array `data` incluye un objeto por cada entidad que debe incluirse en una solicitud de analytics posterior. No debes solicitar analytics para IDs fuera de este conjunto.
+
+Cada objeto incluye cuatro campos: `entity_id`, `activity_start_time`, `activity_end_time` y `placements`. Los tiempos de inicio y fin de actividad representan el rango temporal al que aplican los eventos de cambio de la entidad asociada y, por tanto, determinan las fechas que deben especificarse en las solicitudes de analytics posteriores. El array `placements` puede incluir los siguientes valores: `ALL_ON_TWITTER`, `SPOTLIGHT` y `TREND`. Indica qué placements deben solicitarse para el ID de entidad dado.
+
+#### Uso
+
+El endpoint Active Entities debe dictar cómo se realizan las solicitudes de analytics. Las siguientes directrices de uso están redactadas para apoyar la sincronización de analytics, permitiendo a los partners mantener sus almacenes de datos sincronizados con X. En otras palabras, describe cómo realizar sincronizaciones en segundo plano programadas periódicamente.
+
+Hay dos decisiones que debe tomar un desarrollador.
+
+1. Con qué frecuencia solicitar la información de active entities y, por tanto, con qué frecuencia extraer analytics.
+2. Cómo usar los tiempos de inicio y fin de actividad para determinar los valores `start_time` y `end_time` de la solicitud de analytics.
+
+Estos se discuten con más detalle en cada una de las dos subsecciones, a continuación, tras el resumen.
+
+### Resumen
+
+Usa el endpoint Active Entities de la siguiente manera para dictar cómo se realizan las solicitudes de analytics. Sigue estos pasos una vez que hayas decidido con qué frecuencia solicitar la información de active entities y, por tanto, con qué frecuencia extraer analytics.
+
+1. Haz la solicitud a Active Entities.
+2. Divide la respuesta por placement. Un grupo para `ALL_ON_TWITTER`, uno para `SPOTLIGHT` y otro para `TREND`.
+3. Para cada grupo de placement, haz lo siguiente.
+ 1. Extrae los IDs de entidad.
+ 2. Determina los valores `start_time` y `end_time` de analytics.
+ - Encuentra el `activity_start_time` mínimo. Redondea este valor hacia abajo.
+ - Encuentra el `activity_end_time` máximo. Redondea este valor hacia arriba.
+ 3. Realiza la(s) solicitud(es) de analytics.
+ - Agrupa los IDs de entidad en lotes de 20.
+ - Usa los valores `start_time` y `end_time` del punto #3b.
+ - Especifica el valor de `placement` adecuado.
+ 4. Escribe en tu almacén de datos.
+
+Consulta [active\_entities.py](https://github.com/xdevplatform/twitter-python-ads-sdk/blob/master/examples/active_entities.py) como ejemplo que utiliza el SDK de Python.
+
+### Frecuencia
+
+La respuesta a la primera pregunta determina el rango de tiempo que se debe usar en las solicitudes de Active Entities. Por ejemplo, si solicitas información de active entities cada hora, el rango de tiempo debe ser de una hora. Si solicitas información de active entities una vez al día, el rango de tiempo debe ser de un día. En otras palabras, los rangos de tiempo deben seleccionarse de modo que el `start_time` de la solicitud actual sea igual al `end_time` de la solicitud anterior.
+
+
+ **Nota**: Una ventana de tiempo solo debe solicitarse una vez. Solicitar una ventana de tiempo más de una vez generará solicitudes de analytics innecesarias. (Excepción más abajo).
+
+
+Para los partners que deseen solicitar analytics varias veces por hora para la hora _actual_, aplica el mismo patrón: la frecuencia determina el rango de tiempo. La tabla siguiente muestra timestamps de inicio y fin de Active Entities de ejemplo para este escenario.
+
+| | | |
+| :-- | :-- | :-- |
+| **Hora de la solicitud** | **timestamp `start_time`** | **timestamp `end_time`** |
+| 00:15:00 | 00:00:00 | 00:15:00 |
+| 00:30:00 | 00:15:00 | 00:30:00 |
+| 00:45:00 | 00:30:00 | 00:45:00 |
+| 01:00:00 | 00:45:00 | 01:00:00 |
+
+Dada la forma en que se almacenan los eventos de cambio, las cuatro solicitudes de Active Entities anteriores consultan el mismo bucket horario, lo cual es necesario para este caso de uso. Sin embargo, después de la hora actual, este bucket horario ya no debe consultarse.
+
+### Tiempos de actividad
+
+Recomendamos el siguiente enfoque para trabajar con los tiempos de inicio y fin de actividad. A través de todos los objetos en la respuesta de Active Entities, encuentra el `activity_start_time` mínimo y el `activity_end_time` máximo. Modifica estos valores redondeando hacia abajo el tiempo mínimo de inicio de actividad y redondeando hacia arriba el tiempo máximo de fin de actividad. Concretamente, pon a cero los timestamps en ambos casos y suma un día al tiempo de fin, como se ilustra en la siguiente tabla. Estos son los tiempos de inicio y fin que deben especificarse en las solicitudes de analytics posteriores.
+
+| | |
+| :-- | :-- |
+| **Min, max activity times** | **Tiempos derivados** |
+| 2026-03-04T20:55:20Z
2026-03-05T14:40:59Z | 2026-03-04T00:00:00Z
2026-03-06T00:00:00Z |
+
+**Nota**: Es importante incluir los timestamps con horas, minutos y segundos a cero. De lo contrario, si solo se pasa la fecha, asumiremos que estás solicitando analytics que empiezan y terminan a medianoche en la zona horaria de la cuenta de anuncios, lo que puede no ser deseable. Por ejemplo, si el tiempo mínimo de inicio de actividad es 2026-02-28T01:30:07Z y se omite el timestamp para una cuenta de anuncios con un offset de -08:00:00, la solicitud de analytics omitirá los cambios que ocurrieron entre las 01:30 y las 08:00.
+
+Alternativamente, si prefieres solicitar analytics solo para la ventana de tiempo de actividad devuelta sin expandirla a días completos, puedes hacerlo. Con este enfoque, los tiempos derivados de inicio y fin serían 2026-03-04T20:00:00Z y 2026-03-05T15:00:00Z, respectivamente. (Ten en cuenta que rangos como estos no se aceptan si especificas granularidad `DAY` en la solicitud de analytics).
+
+#### Ejemplo
+
+Esta sección muestra cómo usar Active Entities junto con el endpoint síncrono de analytics. (Las respuestas se han modificado ligeramente para mejorar la legibilidad). En este ejemplo, se llama al endpoint Active Entities al inicio de cada hora, mirando cada solicitud la hora anterior. La respuesta determina cómo se utiliza el endpoint síncrono de analytics.
+
+La primera solicitud de Active Entities se realiza a las 03:00:00. La respuesta indica que las métricas del line item dvcz7 cambiaron y que esos eventos de cambio aplican a la ventana entre 02:02:55 y 02:28:12.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T02:00:00Z&end_time=2026-02-11T03:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": [
+ {
+ "entity_id": "dvcz7",
+ "activity_start_time": "2026-02-11T02:02:55Z",
+ "activity_end_time": "2026-02-11T02:58:12Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ }
+ ]
+ }
+```
+
+Con base en estos tiempos de inicio y fin de actividad y siguiendo el enfoque descrito arriba, los valores `start_time` y `end_time` de analytics se establecen en 2026-02-11T00:00:00Z y 2026-02-12T00:00:00Z, respectivamente. Vemos que el tercer elemento en cada uno de los arrays de métricas debajo es distinto de cero, como esperábamos en función de la información de active entities.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
+```
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 24,
+ "data": [
+ {
+ "id": "dvcz7",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "engagements": [
+ 0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "video_total_views": [
+ 0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ]
+ }
+ }
+ ]
+ }
+ ],
+ "request": {}
+ }
+```
+
+La siguiente solicitud de Active Entities ocurre a las 04:00:00 y solo mira la hora anterior. Como se mencionó antes, una ventana de tiempo solo debe solicitarse una vez. Con base en la respuesta, vemos que los eventos de cambio de este line item aplican _tanto_ a las 02:00:00 como a las 03:00:00. En la solicitud de analytics posterior, esperamos ver cambios para ambas horas.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T03:00:00Z&end_time=2026-02-11T04:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": [
+ {
+ "entity_id": "dvcz7",
+ "activity_start_time": "2026-02-11T02:07:17Z",
+ "activity_end_time": "2026-02-11T03:49:22Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ }
+ ]
+ }
+```
+
+Además de ver métricas distintas de cero para las 03:00:00, observamos que las impresiones, el gasto y las vistas de video MRC se han actualizado respecto a sus valores anteriores. Las impresiones, por ejemplo, ahora son 2.995 para la hora 02:00:00, frente a 2.792 anteriores. Esto demuestra cómo los eventos de cambio que se registraron durante la hora 03:00:00 aplican a la hora 02:00:00.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
+```
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 24,
+ "data": [
+ {
+ "id": "dvcz7",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "engagements": [
+ 0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "video_total_views": [
+ 0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ]
+ }
+ }
+ ]
+ }
+ ],
+ "request": {}
+ }
+```
+
+La solicitud de Active Entities a las 05:00:00, mirando de nuevo solo la hora anterior, muestra que los eventos de cambio aplican únicamente a la hora 03:00:00. Los cambios en las métricas de analytics en la solicitud posterior lo reflejan.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T04:00:00Z&end_time=2026-02-11T05:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": [
+ {
+ "entity_id": "dvcz7",
+ "activity_start_time": "2026-02-11T03:42:39Z",
+ "activity_end_time": "2026-02-11T03:48:48Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ }
+ ]
+ }
+```
+
+La respuesta de analytics muestra que solo las métricas de la hora 03:00:00 han cambiado; los valores para la hora 02:00:00 son los mismos que en la solicitud anterior de analytics.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
+```
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 24,
+ "data": [
+ {
+ "id": "dvcz7",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "engagements": [
+ 0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "video_total_views": [
+ 0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ]
+ }
+ }
+ ]
+ }
+ ],
+ "request": {}
+ }
+```
+
+Finalmente, a las 06:00:00 vemos que no hay eventos de cambio adicionales. **Nota**: Esto _no_ implica que las métricas de este line item no puedan cambiar en el futuro.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T05:00:00Z&end_time=2026-02-11T06:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": []
+ }
+```
+
+### Guía asíncrona
+
+## Referencia de la API
+
+### Asynchronous Analytics
+
+#### Introducción
+
+Los endpoints asíncronos de analytics permiten a partners y anunciantes solicitar métricas enviando solicitudes de creación que el servidor procesa de forma asíncrona. (Nos referimos a estos como "jobs" asíncronos de analytics). Con este enfoque, la conexión del cliente no necesita permanecer abierta hasta que la solicitud sea atendida.
+
+Estos endpoints, al igual que su contraparte síncrona, permiten a partners y anunciantes solicitar estadísticas detalladas sobre el rendimiento de campañas. Admiten solicitar datos para cuentas, instrumentos de financiación, campañas, line items, posts promocionados y creativos de medios. La diferencia entre estos y el endpoint síncrono es que los endpoints asíncronos de analytics admiten rangos de fechas más largos, de hasta 90 días, así como segmentación. Puedes encontrar detalles adicionales sobre las diferencias entre ambos en nuestra página [Analytics Overview](/x-ads-api/analytics).
+
+A diferencia de nuestros endpoints síncronos, el rate limiting se basa en el número de jobs concurrentes para una cuenta determinada. En otras palabras, se basa en el número de jobs que pueden estar en estado de procesamiento en un momento dado. Esto se cuenta a nivel de cuenta de anuncios.
+
+#### Uso
+
+Obtener métricas de campaña usando los endpoints asíncronos de analytics es un proceso de varios pasos. Implica crear un job, comprobar si el job ha terminado de procesarse y, finalmente, descargar los datos. El archivo de datos debe descomprimirse. Los cuatro pasos específicos se describen a continuación.
+
+1. Crea el job usando el endpoint [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics).
+2. Realiza solicitudes a intervalos regulares al endpoint [GET stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) para determinar si el job ha terminado de procesarse.
+3. Una vez que el job haya terminado de procesarse, descarga el archivo de datos.
+4. Descomprime el archivo de datos.
+
+El objeto de respuesta devuelto en el archivo de datos tiene el mismo esquema JSON que la respuesta del endpoint síncrono de analytics.
+
+Las métricas de campaña segmentadas solo están disponibles a través de los endpoints asíncronos de analytics. Las métricas de campaña pueden desglosarse por ubicación, género, interés, palabra clave y más. Para una lista completa de opciones, consulta la página [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation). Para solicitar métricas segmentadas, utiliza el parámetro de solicitud `segmentation_type` al crear el job.
+
+#### Ejemplo
+
+Esta sección demuestra cómo usar los endpoints asíncronos de analytics.
+
+Empieza creando un job usando el endpoint [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics). El ejemplo siguiente solicita métricas de engagement —como impresiones, likes, clics, etc.— para un line item específico durante el lapso de una semana. (Ten en cuenta que el rango de tiempo solicitado llega hasta, pero no incluye, el 20 de marzo, ya que el timestamp se establece a medianoche).
+
+```text
+$ twurl -X POST -H ads-api.x.com "/12/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2026-03-12T00:00:00Z&end_time=2026-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"
+```
+
+```json
+ {
+ "request": {
+ "params": {
+ "start_time": "2026-03-12T00:00:00Z",
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "placement": "ALL_ON_TWITTER",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ },
+ "data": {
+ "start_time": "2026-03-12T00:00:00Z",
+ "segmentation_type": null,
+ "url": null,
+ "id_str": "1120829647711653888",
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "id": 1120829647711653888,
+ "expires_at": null,
+ "account_id": "18ce54d4x5t",
+ "status": "PROCESSING",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "created_at": "2026-04-01T23:19:46Z",
+ "platform": null,
+ "updated_at": "2026-04-01T23:19:46Z",
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ }
+```
+
+Esta respuesta no devuelve las métricas del line item. Simplemente proporciona información sobre el job que acabas de crear. El ID del job es necesario para verificar el estado del job. Esto se muestra tanto en los atributos de respuesta `id` como `id_str`.
+
+A continuación, querrás comprobar si el job que has creado, usando el `id_str` de la respuesta anterior, ha terminado de procesarse, lo cual se indica con `"status": "SUCCESS"` en la respuesta. Esto significa que los datos están listos para descargarse. El campo `url` contiene el enlace de descarga.
+
+```text
+$ twurl -H ads-api.x.com "/12/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"
+```
+
+```json
+ {
+ "request": {
+ "params": {
+ "job_ids": [
+ 1120829647711653888
+ ]
+ }
+ },
+ "next_cursor": "1120828505715920896",
+ "data": [
+ {
+ "start_time": "2026-03-12T00:00:00Z",
+ "segmentation_type": null,
+ "url": "https://ton.twimg.com/advertiser-api-async-analytics/stats_job_1120829647711653888.json.gz",
+ "id_str": "1120829647711653888",
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "id": 1120829647711653888,
+ "expires_at": "2026-04-03T23:19:48Z",
+ "account_id": "18ce54d4x5t",
+ "status": "SUCCESS",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "created_at": "2026-04-01T23:19:46Z",
+ "platform": null,
+ "updated_at": "2026-04-01T23:19:48Z",
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ ]
+ }
+```
+
+Aunque en el ejemplo anterior estamos pasando un único ID de job, en la práctica querrás usar el parámetro `job_ids` para comprobar el estado de múltiples jobs a la vez, especificando hasta 200 IDs de job.
+
+A continuación, descarga el archivo de datos usando el valor `url` indicado.
+
+```text
+ $ wget https://ton.twimg.com/advertiser-api-async-analytics/stats_job_1120829647711653888.json.gz
+```
+
+Finalmente, descomprime el archivo de datos.
+
+```text
+`$ gunzip stats_job_1120829647711653888.json.gz`
+```
+
+El contenido del archivo se muestra a continuación.
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 1,
+ "data": [
+ {
+ "id": "el32n",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 3482
+ ],
+ "tweets_send": null,
+ "qualified_impressions": null,
+ "follows": null,
+ "app_clicks": null,
+ "retweets": [
+ 102
+ ],
+ "unfollows": null,
+ "likes": [
+ 15
+ ],
+ "engagements": [
+ 171
+ ],
+ "clicks": [
+ 30
+ ],
+ "card_engagements": null,
+ "poll_card_vote": null,
+ "replies": null,
+ "carousel_swipes": null
+ }
+ }
+ ]
+ }
+ ],
+ "request": {
+ "params": {
+ "start_time": "2026-03-12T00:00:00Z",
+ "segmentation_type": null,
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "platform": null,
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ }
+ }
+```
+
+### Reach y frecuencia promedio
+
+
+
+#### GET stats/accounts/:account\_id/reach/campaigns
+
+Obtén analytics de reach y frecuencia promedio para las campañas especificadas.
+
+### URL del recurso
+
+`https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns`
+
+### Parámetros
+
+| Nombre | Descripción |
+| :-- | :-- |
+| account\_id _required_ | El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y generalmente es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto [GET accounts](/x-ads-api/campaign-management/reference#accounts). La cuenta especificada debe estar asociada al usuario autenticado.
Tipo: string
Ejemplo: `18ce54d4x5t` |
+| campaign\_ids _required_ | Acota la respuesta solo a las campañas deseadas especificando una lista de identificadores separados por comas. Pueden proporcionarse hasta 20 IDs.
**Nota**: Pueden proporcionarse hasta 20 IDs de campaña.
Tipo: string
Ejemplo: `8fgzf` |
+| end\_time _required_ | Acota los datos obtenidos a la hora de fin especificada, expresada en [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Nota**: Debe expresarse en horas completas (0 minutos y 0 segundos).
Tipo: string
Ejemplo: `2026-05-26T07:00:00Z` |
+| start\_time _required_ | Acota los datos obtenidos a la hora de inicio especificada, expresada en [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Nota**: Debe expresarse en horas completas (0 minutos y 0 segundos).
Tipo: string
Ejemplo: `2026-05-19T07:00:00Z` |
+
+### Solicitud de ejemplo
+
+`GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2026-05-19&end_time=2026-05-26`
+
+### Respuesta de ejemplo
+
+```json
+ {
+ "request": {
+ "params": {
+ "campaign_ids": [
+ "8fgzf"
+ ],
+ "start_time": "2026-05-19T00:00:00Z",
+ "end_time": "2026-05-26T00:00:00Z",
+ "account_id": "18ce54d4x5t"
+ }
+ },
+ "data_type": "reach",
+ "data": [
+ {
+ "id": "8fgzf",
+ "total_audience_reach": 1217,
+ "average_frequency": 1.01
+ }
+ ]
+ }
+```
+
+#### GET stats/accounts/:account\_id/reach/funding\_instruments
+
+Obtén analytics de reach y frecuencia promedio para los instrumentos de financiación especificados.
+
+### URL del recurso
+
+`https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments`
+
+### Parámetros
+
+| Nombre | Descripción |
+| :-- | :-- |
+| account\_id _required_ | El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y generalmente es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto [GET accounts](/x-ads-api/campaign-management/reference#accounts). La cuenta especificada debe estar asociada al usuario autenticado.
Tipo: string
Ejemplo: `18ce54d4x5t` |
+| funding\_instrument\_ids _required_ | Acota la respuesta solo a los instrumentos de financiación deseados especificando una lista de identificadores separados por comas. Pueden proporcionarse hasta 20 IDs.
**Nota**: Pueden proporcionarse hasta 20 IDs de instrumentos de financiación.
Tipo: string
Ejemplo: `lygyi` |
+| end\_time _required_ | Acota los datos obtenidos a la hora de fin especificada, expresada en [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Nota**: Debe expresarse en horas completas (0 minutos y 0 segundos).
Tipo: string
Ejemplo: `2026-05-26T07:00:00Z` |
+| start\_time _required_ | Acota los datos obtenidos a la hora de inicio especificada, expresada en [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Nota**: Debe expresarse en horas completas (0 minutos y 0 segundos).
Tipo: string
Ejemplo: `2026-05-19T07:00:00Z` |
+
+### Solicitud de ejemplo
+
+```text
+GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2026-05-19&end_time=2026-05-26
+```
+
+### Respuesta de ejemplo
+
+```json
+ {
+ "request": {
+ "params": {
+ "funding_instrument_ids": [
+ "lygyi"
+ ],
+ "start_time": "2026-05-19T00:00:00Z",
+ "end_time": "2026-05-26T00:00:00Z",
+ "account_id": "18ce54d4x5t"
+ }
+ },
+ "data_type": "reach",
+ "data": [
+ {
+ "id": "lygyi",
+ "total_audience_reach": 1217,
+ "average_frequency": 1.01
+ }
+ ]
+ }
+```
+
+### Synchronous Analytics
+
+
+
+#### GET stats/accounts/:account\_id
+
+Obtén analytics síncronos para la cuenta actual. Se permite un rango de tiempo máximo (`end_time` - `start_time`) de 7 días.
+
+### URL del recurso
+
+`https://ads-api.x.com/12/stats/accounts/:account_id`
+
+### Parámetros
+
+| Nombre | Descripción |
+| :-- | :-- |
+| account\_id _required_ | El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y generalmente es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto [GET accounts](/x-ads-api/campaign-management/reference#accounts). La cuenta especificada debe estar asociada al usuario autenticado.
Tipo: string
Ejemplo: `18ce54d4x5t` |
+| end\_time _required_ | Acota los datos obtenidos a la hora de fin especificada, expresada en [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Nota**: Debe expresarse en horas completas (0 minutos y 0 segundos).
Tipo: string
Ejemplo: `2026-05-26T07:00:00Z` |
+| entity _required_ | El tipo de entidad para el que se obtendrán los datos.
Tipo: enum
Valores posibles: `ACCOUNT`, `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET` |
+| entity\_ids _required_ | Las entidades específicas para las que se obtendrán los datos. Especifica una lista de IDs de entidad separados por comas.
**Nota**: Pueden proporcionarse hasta 20 IDs de entidad.
Tipo: string
Ejemplo: `8u94t` |
+| granularity _required_ | Especifica qué tan granulares deben ser los datos obtenidos.
Tipo: enum
Valores posibles: `DAY`, `HOUR`, `TOTAL` |
+| metric\_groups _required_ | Las métricas específicas que deben devolverse. Especifica una lista de grupos de métricas separados por comas. Para más información, consulta [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation).
**Nota**: Los datos de `MOBILE_CONVERSION` deben solicitarse por separado.
Tipo: enum
Valores posibles: `BILLING`, `ENGAGEMENT`, `LIFE_TIME_VALUE_MOBILE_CONVERSION`, `MOBILE_CONVERSION`, `VIDEO`, `WEB_CONVERSION` |
+| placement _required_ | Acota los datos obtenidos a un placement determinado.
**Nota**: Solo se acepta un único valor por solicitud. Para entidades que tengan placement tanto en X como en X Audience Platform, se requieren solicitudes separadas, una para cada valor de placement.
Tipo: enum
Valores posibles: `ALL_ON_TWITTER`, `SPOTLIGHT`, `TREND` |
+| start\_time _required_ | Acota los datos obtenidos a la hora de inicio especificada, expresada en [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Nota**: Debe expresarse en horas completas (0 minutos y 0 segundos).
Tipo: string
Ejemplo: `2026-05-19T07:00:00Z` |
+
+### Solicitud de ejemplo
+
+```text
+GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2026-05-19&end_time=2026-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT
+```
+
+### Respuesta de ejemplo
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 1,
+ "data": [
+ {
+ "id": "8u94t",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 1233
+ ],
+ "tweets_send": null,
+ "qualified_impressions": null,
+ "follows": null,
+ "app_clicks": null,
+ "retweets": null,
+ "likes": [
+ 1
+ ],
+ "engagements": [
+ 58
+ ],
+ "clicks": [
+ 58
+ ],
+ "card_engagements": null,
+ "poll_card_vote": null,
+ "replies": null,
+ "carousel_swipes": null
+ }
+ }
+ ]
+ }
+ ],
+ "request": {
+ "params": {
+ "start_time": "2026-05-19T07:00:00Z",
+ "segmentation_type": null,
+ "entity_ids": [
+ "8u94t"
+ ],
+ "end_time": "2026-05-26T07:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "platform": null,
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ }
+ }
+```
+
+### Active Entities
+
+
+
+#### GET stats/accounts/:account\_id/active\_entities
+
+Obtén detalles sobre qué métricas de analytics de qué entidades han cambiado en un período de tiempo determinado.
+
+Este endpoint debe usarse junto con nuestros endpoints de analytics. Los resultados de este endpoint indican para qué entidades de anuncios se debe solicitar analytics. Consulta nuestra [Guía de Active Entities](/x-ads-api/analytics#active-entities) para conocer las directrices de uso.
+
+Los eventos de cambio están disponibles en buckets horarios.
+
+- Los valores `start_time` y `end_time` especifican qué buckets horarios se consultan.
+- El array `data` devuelto incluirá un objeto por cada entidad que deba incluirse en solicitudes de analytics posteriores.
+- **IMPORTANTE**: Las fechas que deben especificarse en solicitudes de analytics posteriores deben determinarse en función de los valores `activity_start_time` y `activity_end_time`.
+ - Estos valores representan los rangos de tiempo a los que _aplican_ los eventos de cambio almacenados. Esto se devuelve por entidad.
+
+**Nota**: Se permite un rango de tiempo máximo (`end_time` - `start_time`) de 90 días.
+
+### URL del recurso
+
+`https://ads-api.x.com/12/stats/accounts/:account_id/active_entities`
+
+### Parámetros
+
+| Nombre | Descripción |
+| :-- | :-- |
+| account\_id _required_ | El identificador de la cuenta utilizada. Aparece dentro de la ruta del recurso y generalmente es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto [GET accounts](/x-ads-api/campaign-management/reference#accounts). La cuenta especificada debe estar asociada al usuario autenticado.
Tipo: string
Ejemplo: `18ce54d4x5t` |
+| end\_time _required_ | Acota los datos obtenidos a la hora de fin especificada, expresada en [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Nota**: Debe expresarse en horas completas (0 minutos y 0 segundos).
Tipo: string
Ejemplo: `2026-05-26T07:00:00Z` |
+| entity _required_ | El tipo de entidad para el que se obtendrán los datos.
Tipo: enum
Valores posibles: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET` |
+| start\_time _required_ | Acota los datos obtenidos a la hora de inicio especificada, expresada en [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Nota**: Debe expresarse en horas completas (0 minutos y 0 segundos).
Tipo: string
Ejemplo: `2026-05-19T07:00:00Z` |
+| campaign\_ids _optional_ | Acota la respuesta solo a las entidades asociadas con las campañas deseadas, especificando una lista de identificadores separados por comas. Pueden proporcionarse hasta 200 IDs.
**Nota**: Excluyente con `funding_instrument_ids` y `line_item_ids`.
Tipo: string
Ejemplo: `8wku2` |
+| funding\_instrument\_ids _optional_ | Acota la respuesta solo a las entidades asociadas con los instrumentos de financiación deseados, especificando una lista de identificadores separados por comas. Pueden proporcionarse hasta 200 IDs.
**Nota**: Excluyente con `campaign_ids` y `line_item_ids`.
Tipo: string
Ejemplo: `lygyi` |
+| line\_item\_ids _optional_ | Acota la respuesta solo a las entidades asociadas con los line items deseados, especificando una lista de identificadores separados por comas. Pueden proporcionarse hasta 200 IDs.
**Nota**: Excluyente con `campaign_ids` y `line_item_ids`.
例: `8v7jo` |
+
+### リクエスト例
+
+`GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2026-02-28&end_time=2026-03-01`
+
+### レスポンス例
+
+```json
+ {
+ "request": {
+ "params": {
+ "account_id": "18ce54d4x5t",
+ "entity": "PROMOTED_TWEET",
+ "start_time": "2026-02-28T08:00:00Z",
+ "end_time": "2026-03-01T08:00:00Z"
+ }
+ },
+ "data": [
+ {
+ "entity_id": "2mvb28",
+ "activity_start_time": "2026-02-28T01:30:07Z",
+ "activity_end_time": "2026-03-01T07:42:55Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ },
+ {
+ "entity_id": "2mvb29",
+ "activity_start_time": "2026-02-27T11:30:07Z",
+ "activity_end_time": "2026-03-01T07:42:50Z",
+ "placements": [
+ "ALL_ON_TWITTER",
+ "PUBLISHER_NETWORK"
+ ]
+ },
+ {
+ "entity_id": "2mvfan",
+ "activity_start_time": "2026-02-27T09:00:05Z",
+ "activity_end_time": "2026-03-01T06:06:36Z",
+ "placements": [
+ "PUBLISHER_NETWORK"
+ ]
+ },
+ {
+ "entity_id": "2n17dx",
+ "activity_start_time": "2026-02-28T02:02:26Z",
+ "activity_end_time": "2026-03-01T07:52:44Z",
+ "placements": [
+ "ALL_ON_TWITTER",
+ "PUBLISHER_NETWORK"
+ ]
+ }
+ ]
+ }
+```
diff --git a/ko/x-ads-api/analytics.mdx b/ko/x-ads-api/analytics.mdx
new file mode 100644
index 000000000..66a4aea35
--- /dev/null
+++ b/ko/x-ads-api/analytics.mdx
@@ -0,0 +1,1263 @@
+---
+title: "분석(Analytics)"
+keywords: ["광고 분석", "ads analytics", "캠페인 분석", "광고 지표", "광고 메트릭", "캠페인 성과"]
+description: "동기 및 비동기 분석 엔드포인트와 세분화·그래뉼래리티 옵션을 활용해 X Ads API에서 캠페인 성과 지표를 가져옵니다."
+---
+
+분석 지표는 파트너와 광고주가 X에서 프로모션 중인 콘텐츠의 성과를 이해하는 데 도움이 됩니다. 여기에는 노출 수, 클릭 수, 동영상 조회 수, 지출 금액과 같은 정보가 포함됩니다. 또한 파트너와 광고주는 도달한 오디언스의 다양한 세그먼트에 대한 상세 지표도 얻을 수 있습니다.
+
+Ads API는 캠페인 성과 지표를 가져오는 두 가지 방식, 즉 동기와 비동기 방식을 지원합니다. 동기 분석 호출에서는 요청한 지표가 응답에 그대로 반환됩니다. 비동기 분석 엔드포인트에서는 연결된 "작업(job)"이 처리 완료된 후 다운로드 가능한 결과 파일에서 요청한 지표를 받을 수 있습니다. 동기 엔드포인트는 짧은 기간을 지원하며 실시간 캠페인 최적화에 이상적입니다. 비동기 엔드포인트는 훨씬 더 긴 기간을 지원하므로 더 많은 데이터를 가져오는 데 사용되며, 리포트 생성이나 과거 데이터 백필에 적합합니다.
+
+## 세부 사항
+
+### 동기 vs. 비동기
+
+동기와 비동기 분석 엔드포인트의 차이점은 다음 표에 요약되어 있습니다. 이 정보는 개발자가 어떤 엔드포인트 세트를 사용할지 선택하는 데 도움이 되도록 제공됩니다.
+
+| 기능 | 동기 | 비동기 |
+| :-- | :-- | :-- |
+| 속도 제한 | 사용자 수준: 15분당 250 요청 | 계정 수준: 동시\\* 작업 100개 |
+| 기간 | 7일 | 90일(비세분화) 45일(세분화) |
+| 세분화 | 미지원 | 지원 |
+| 응답 반환 | 지표 데이터 | 작업의 처리 상태\\*\\* |
+| 권장 사용 사례 | 실시간 최적화 사용자 인터페이스 요청 | 정기적으로 예약된 동기화 과거 데이터 백필 |
+
+
+ \* 이는 특정 시점에 처리 중 상태로 있을 수 있는 작업의 최대 수를 의미합니다.
+
+ \*\* 작업이 처리에 성공적으로 완료되면 URL이 반환됩니다. 이 URL에서 압축된(gzip) 결과 파일을 다운로드할 수 있습니다.
+
+ 이를 제외하면 두 엔드포인트는 동일한 기능을 제공합니다.
+
+
+### 사용 사례
+
+주요 분석 사용 사례는 세 가지입니다.
+
+1. 실시간 최적화: 성과 지표를 활용하여 활성 캠페인 업데이트
+2. 동기화: 정기적으로 예약된 백그라운드 동기화
+3. 신규 계정 온보딩: 과거 데이터 백필
+
+동기 분석 엔드포인트는 최근 5~15분 이내의 지표 변화에 기반하여 캠페인을 업데이트하는 실시간 최적화에 사용할 수 있습니다. 두 엔드포인트 모두 분석 동기화에 사용할 수 있습니다. 원하는 기간과 세분화 필요 여부에 따라 사용할 엔드포인트가 결정됨을 염두에 두세요. 신규 계정 온보딩은 비동기 분석 엔드포인트로만 수행해야 합니다. (동기 분석 엔드포인트는 대량의 데이터를 가져오는 데 사용해서는 안 됩니다.)
+
+비동기 분석 엔드포인트는 지표가 백엔드 프로세스와 동기화되어 있는 경우 대시보드와 기타 UI 요소를 구동할 수 있습니다. 사용자 인터페이스 요청을 충족시키기 위해 비동기 분석 엔드포인트를 호출하지 않도록 구현해야 합니다.
+
+### 요청 옵션
+
+분석 요청은 광고 계정 범위로 제한되므로 리소스 경로에 계정 ID가 필요합니다. 아래에 나열된 요청 옵션은 쿼리 파라미터로 지정합니다. 다음 유형의 값이 필요합니다.
+
+- Entities: 분석을 요청할 엔티티 유형 및 최대 20개의 엔티티 ID
+- 기간: 시작 및 종료 시각, ISO 8601로 표현
+ - **참고:** 정시 단위(whole hours)로 표현해야 합니다
+- 지표 그룹(Metric groups): 관련 지표의 하나 이상의 집합(각 지표 그룹 내 지표 목록은 Metrics and Segmentation 참고)
+- 그래뉼래리티(Granularity): 지표가 반환되어야 하는 집계 수준 지정
+- 게재 위치(Placement): X 내에서 게재된 광고와 외부에서 게재된 광고 중 어디에서 지표를 가져올지 결정
+ - **참고:** 요청당 단일 게재 위치 값만 지정할 수 있습니다
+
+기간을 지정하려면 `start_time`과 `end_time` 요청 파라미터를 사용하세요. 이 값들은 지정된 그래뉼래리티에 따라 다음과 같이 정렬되어야 합니다.
+
+1. `TOTAL`: 임의 기간 지정(엔드포인트의 제한 내)
+2. `DAY`: 시작 시각과 종료 시각 모두 계정의 시간대 기준 자정에 정렬되어야 함
+3. `HOUR`: 임의 기간 지정(엔드포인트의 제한 내)
+
+종료 시각은 미포함(exclusive)입니다. 예를 들어 `start_time=2026-01-01T00:00:00Z`와 `end_time=2026-01-02T00:00:00Z`로 요청하면, 이 기간은 24시간만을 포함하므로 (이틀이 아니라) 하루치 분석 지표가 반환됩니다.
+
+**세분화(Segmentation)**
+
+세분화는 비동기 분석 엔드포인트에서만 사용할 수 있으며, 파트너와 광고주가 특정 타깃팅 값별로 분리된 지표를 가져올 수 있게 해줍니다. 세분화된 지표를 요청하려면 `segmentation_type` 요청 파라미터를 사용하세요. 세분화 옵션에 대한 자세한 내용은 [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation)을 참고하세요.
+
+## FAQ
+
+Ads API 수치가 X Ads UI에 표시되는 값과 일치하지 않는 이유는 무엇인가요?
+
+- 모든 게재 위치(`ALL_ON_TWITTER`, `SPOTLIGHT`, `TREND`)에 대한 데이터를 요청했는지 확인하세요.
+- Ads API의 종료 시각은 미포함이며, Ads UI에서는 포함이라는 점을 기억하세요.
+
+데이터를 요청한 시점에 따라 수치가 변하는 이유는 무엇인가요?
+
+- 리포팅 지표는 사용 가능해지는 즉시 가져올 수 있습니다. 이는 거의 실시간으로 제공됩니다. 다만 초기 결과는 추정치이므로 변경될 수 있습니다. 지출 데이터를 제외하면 지표는 24시간 후에 확정됩니다.
+- 지출 지표는 일반적으로 이벤트로부터 3일 이내에 확정됩니다. 그러나 (예: 스팸 필터링을 위해) 이벤트 발생일로부터 최대 14일까지 청구 데이터를 처리합니다.
+
+특정 기간에 대해 어떤 엔티티 ID를 요청할지 어떻게 결정하나요?
+
+- [Active Entities 엔드포인트](/x-ads-api/analytics#active-entities-2)를 사용하세요.
+
+분석 응답의 모든 값이 `null`인 이유는 무엇인가요?
+
+- 요청한 기간 동안 캠페인이 게재되지 않았을 가능성이 큽니다.
+- [Active Entities 엔드포인트](/x-ads-api/analytics#active-entities-2)를 사용하여 어떤 엔티티에 대해 어떤 기간 동안 분석을 가져올지 결정하세요.
+
+API는 `null` 값을 표시하는데 UI에서는 0으로 표시되는 이유는 무엇인가요?
+
+- UI는 이러한 값을 0으로 표시하지만, 두 값은 동등합니다.
+
+X 타임라인과 같은 세분화된 게재 위치와 관련된 지표를 어떻게 요청할 수 있나요?
+
+- 분석에서는 다음 게재 위치 값을 지원합니다: `ALL_ON_TWITTER`, `SPOTLIGHT`, `TREND`.
+
+삭제되거나 일시중지된 엔티티에 대한 지표를 가져올 수 있나요?
+
+- 네. 엔티티의 상태는 분석 지표의 가용성에 영향을 주지 않습니다.
+
+세분화된 값이 비세분화된 값과 일치하지 않는 이유는 무엇인가요?
+
+- 이 정보가 도출되는 방식 때문에, 세분화된 데이터는 비세분화된 데이터로 100% 합산되지 _않을_ 수 있습니다.
+
+API의 세분화된 값이 Ads Manager UI에 표시되는 값과 일치하지 않는 이유는 무엇인가요?
+
+- API는 쿼리한 특정 엔티티 유형(CAMPAIGN, PROMOTED\_TWEET)에 한정된 세분화 지표를 반환합니다. Ads Manager UI는 엔티티 유형 간 데이터를 집계합니다. 이는 동일한 기반 데이터의 다른 관점이며 예상된 동작입니다.
+
+여러 차원으로 세분화된 데이터를 요청할 수 있나요?
+
+- 다차원 세분화는 지원하지 않습니다.
+
+## 모범 사례
+
+Ads API에서 [분석](/x-ads-api/analytics) 데이터를 수집할 때의 몇 가지 모범 사례입니다.
+
+### 속도 제한 및 재시도
+
+- 속도 제한된 쿼리(`HTTP 429` 상태 코드를 반환하는 쿼리)에서는 `x-rate-limit-reset` 헤더를 확인하고, 표시된 시각 이후에만 재시도해야 합니다.
+- HTTP 503 Service Unavailable 상태 코드가 반환된 쿼리에서는 `retry-after` 헤더를 확인하고, 표시된 시간 이후에만 재시도해야 합니다.
+- 재시도에 표시된 시간을 준수하지 않는 애플리케이션은 통보 없이 Ads API 접근 권한이 취소되거나 제한될 수 있습니다.
+
+### 분석 지표 요약
+
+- 모든 분석 지표는 24시간 후에 잠기며, `billed_charge_local_micro`를 제외하고는 변경되지 않습니다.
+- `billed_charge_local_micro` 지표는 데이터가 반환된 후 최대 3일까지 추정치입니다.
+- 24시간 후에 이 지표는 과지출(`end_time` 이후 게재된 광고)에 대한 크레딧과 무효로 판정된 청구 이벤트 때문에 감소할 수 있습니다. 이 지표는 24시간 이후에는 매우 미미하게 변동합니다.
+- 자세한 내용은 [분석(Analytics)](/x-ads-api/analytics)을 참고하세요.
+
+### 실시간 비세분화 데이터 가져오기
+
+- 항상 `start_time`과 `end_time`을 모두 제공하세요.
+- 7일이 지난 엔티티의 데이터는 가져오지 마세요.
+- 지표를 항상 집계하여 `DAY` 및 `TOTAL` 그래뉼래리티로 합산할 수 있으므로, 가능하면 `HOUR` 그래뉼래리티로 데이터를 요청하세요.
+- 광고 엔티티 계층 구조 전체(예: 캠페인, 자금 조달 수단(funding instrument), 계정 수준)의 합계를 얻기 위해 이러한 지표를 항상 집계하여 합산할 수 있으므로, 가능하면 `line_items` 및 `promoted_tweets` 수준에서 데이터를 요청하세요.
+- 분석 지표의 값을 로컬에 저장하고 보관하세요.
+- 30일이 지난 데이터에 대해 반복적으로 쿼리하지 마세요. 이 데이터는 변경되지 않으므로 로컬에 저장해야 합니다.
+- 모든 비세분화 데이터는 실시간이며, 이벤트 발생 후 수 초 내에 데이터를 사용할 수 있어야 합니다.
+- 전환 지표와 비전환 지표를 별도의 요청으로 묶으세요.
+
+### 세분화된 데이터 가져오기
+
+- 위의 "실시간 비세분화 데이터 가져오기"에 제공된 가이드라인을 참고하세요. 아래에 추가적인 조언이 제공됩니다.
+- 대부분의 세분화 데이터 유형은 데이터가 완전해지기까지 최대 1시간이 걸릴 수 있습니다. `INTERESTS`로 세분화된 데이터는 최대 12시간까지 지연될 수 있습니다.
+- 이 정보가 도출되는 방식 때문에, 세분화된 데이터는 비세분화된 데이터로 100% 합산되지 않을 수 있습니다.
+
+### 과거 데이터 가져오기
+
+- 데이터 백필 시(예: 신규 광고주 계정 추가)에는 더 작은 `start_time` 및 `end_time` 청크로 여러 번 요청해야 할 수 있습니다.
+- 가져오기는 30일 단위의 기간으로 제한하세요.
+- 이러한 가져오기에 대한 속도 제한을 모두 소진하지 않도록 요청을 조절하고 시간에 걸쳐 분산하세요.
+
+### 샘플
+
+이러한 모범 사례 중 일부를 보여주는 샘플 스크립트(`fetch_stats`)는 [ads-platform-tools GitHub](https://github.com/xdevplatform/ads-platform-tools) 리포지토리에서 확인할 수 있습니다.
+
+## 목표별 지표
+
+엔티티에 어떤 지표가 적용되는지는 [캠페인 목표](/x-ads-api/campaign-management)에 따라 다릅니다. 이 가이드를 사용해 각 목표 유형에 대해 가져와야 할 관련 지표 그룹과 추가 파생 지표를 계산하는 방법을 확인하세요.
+
+### `ENGAGEMENTS`
+
+**관련 지표 그룹:**`ENGAGEMENT` 및 `BILLING`.
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| Engagement Rate | `engagements/impressions` |
+| CPE | `billed_charge_local_micro/engagements` |
+
+### `WEBSITE_CLICKS` 및 `WEBSITE_CONVERSIONS`
+
+**관련 지표 그룹:**`ENGAGEMENT`, `BILLING`, `WEB_CONVERSION`.
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Click Rate | `clicks/impressions` |
+| CPLC | `billed_charge_local_micro/clicks` |
+| Total Conversions | `conversion_custom` \+ `conversion_site_visits` \+ `conversion_sign_ups` \+ `conversion_downloads` \+ `conversion_purchases` |
+| Conversion Rate | Total Conversions / `impressions` |
+| CPA | `billed_charge_local_micro` / Total Conversions |
+
+### `APP_INSTALLS`
+
+**관련 지표 그룹:**`ENGAGEMENT`, `BILLING`, `MOBILE_CONVERSION`, `LIFE_TIME_VALUE_MOBILE_CONVERSION`. 크리에이티브에 비디오 앱 카드가 사용된 경우 `VIDEO`도 적용됩니다.
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| App Click Rate | `app_clicks/impressions` |
+| CPAC | `billed_charge_local_micro/app_clicks` |
+| CPI | `billed_charge_local_micro/mobile_conversion_installs` |
+
+### `FOLLOWERS`
+
+**관련 지표 그룹:**`ENGAGEMENT` 및 `BILLING`.
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Follow Rate | `follows/impressions` |
+| CPF | `billed_charge_local_micro/follows` |
+
+### `VIDEO_VIEWS`
+
+**관련 지표 그룹:**`ENGAGEMENT`, `BILLING`, `VIDEO`.
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Video Rate | `video_total_views/impressions` |
+| Cost Per View | `billed_charge_local_micro/video_total_views` |
+
+### `VIDEO_VIEWS_PREROLL`
+
+**관련 지표 그룹:**`ENGAGEMENT`, `BILLING`, `VIDEO`.
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Video Rate | `video_total_views/impressions` |
+| Cost Per View | `billed_charge_local_micro/video_total_views` |
+
+## 지표 및 세분화
+
+이 문서는 각 엔티티 유형별로 [분석(Analytics)](/x-ads-api/analytics)에서 사용 가능한 지표와, 각 지표에 대해 사용 가능한 세분화에 대한 개요입니다.
+
+| | | | | | | |
+| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
+| | 지표 그룹 | | | | | |
+| 엔티티 | [`ENGAGEMENT`](#engagement) | [`BILLING`](#BILLING) | [`VIDEO`](#VIDEO) | [`WEB_CONVERSION`](#WEB_CONVERSION) | [`MOBILE_CONVERSION`](#MOBILE_CONVERSION) | [`LIFE_TIME_VALUE_MOBILE_CONVERSION`](#LIFE_TIME_VALUE_MOBILE_CONVERSION) |
+| `ACCOUNT` | ✔\\* | | | | | |
+| `FUNDING_INSTRUMENT` | ✔\\* | ✔ | | | | |
+| `CAMPAIGN` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| `LINE_ITEM` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| `PROMOTED_TWEET` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+
+\*`ENGAGEMENT` 지표 패밀리의 일부 지표는 계정 및 자금 조달 수단 수준에서 사용할 수 없습니다. 자세한 내용은 `ENGAGEMENT` 섹션을 참고하세요.
+
+### 지표 그룹별 사용 가능한 지표
+
+#### `ENGAGEMENT`
+
+| | | | | |
+| :-- | :-- | :-- | :-- | :-- |
+| 지표 | 설명 | 세분화 가능 | 데이터 유형 | Account / Funding Instrument에서 사용 가능 |
+| `engagements` | 총 인게이지먼트 수 | ✔ | Array of ints | ✔ |
+| `impressions` | 총 노출 수 | ✔ | Array of ints | ✔ |
+| `retweets` | 총 리포스트 수 | ✔ | Array of ints | ✔ |
+| `replies` | 총 답글 수 | ✔ | Array of ints | ✔ |
+| `likes` | 총 좋아요 수 | ✔ | Array of ints | ✔ |
+| `follows` | 총 팔로우 수 | ✔ | Array of ints | ✔ |
+| `card_engagements` | 총 카드 인게이지먼트 수 | ✔ | Array of ints | |
+| `clicks` | 좋아요 및 기타 인게이지먼트를 포함한 총 클릭 수 | ✔ | Array of ints | |
+| `app_clicks` | 앱 설치 또는 앱 열기 시도 수 | ✔ | Array of ints | |
+| url\_clicks | 광고 내 링크 또는 Website Card에 대한 총 클릭 수(획득 클릭 포함). | ✔ | Array of ints | |
+| `qualified_impressions` | 총 qualified impressions 수 | ✔ | Array of ints | |
+| `carousel_swipes` | Carousel 이미지 또는 동영상에 대한 총 스와이프 수 | ✔ | Array of ints | |
+
+#### `BILLING`
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| 지표 | 설명 | 세분화 가능 | 데이터 유형 |
+| `billed_engagements` | 청구된 총 인게이지먼트 수 | ✔ | Array of ints |
+| `billed_charge_local_micro` | 총 지출(마이크로 단위) | ✔ | Array of ints |
+
+#### `VIDEO`
+
+비디오 지표 정의 변경에 대한 안내:
+
+`VIDEO` 지표 그룹 내 `video_total_views` 지표는 MRC 표준에 따라 50% 이상이 2초 동안 화면에 노출된 모든 조회를 리포트합니다.
+
+기존의 비디오 조회 정의(100% 노출 상태에서 최소 3초)는 `VIDEO` 지표 그룹의 새로운 `video_3s100pct_views` 지표로 계속 제공됩니다. 기존 조회 정의에 기반하여 입찰하고 청구되려면 새롭게 제공되는 `VIEW_3S_100PCT` bid\_unit을 사용하세요.
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| 지표 | 설명 | 세분화 가능 | 데이터 유형 |
+| `video_total_views` | 총 동영상 조회 수 | ✔ | Array of ints |
+| `video_views_25` | 동영상의 25% 이상이 조회된 총 조회 수. | ✔ | Array of ints |
+| `video_views_50` | 동영상의 50% 이상이 조회된 총 조회 수. | ✔ | Array of ints |
+| `video_views_75` | 동영상의 75% 이상이 조회된 총 조회 수. | ✔ | Array of ints |
+| `video_views_100` | 동영상의 100% 이상이 조회된 총 조회 수. | ✔ | Array of ints |
+| `video_cta_clicks` | call to action에 대한 총 클릭 수 | ✔ | Array of ints |
+| `video_content_starts` | 동영상 재생 시작 총 수 | ✔ | Array of ints |
+| `video_3s100pct_views` | 100% 노출 상태에서 최소 3초 동안 재생된 총 조회 수(레거시 `video_total_views`) | ✔ | Array of ints |
+| `video_6s_views` | 동영상의 6초 이상이 조회된 총 조회 수 | ✔ | Array of ints |
+| `video_15s_views` | 동영상의 15초 이상 또는 전체 재생 시간의 95% 이상이 조회된 총 조회 수 | ✔ | Array of ints |
+
+#### `WEB_CONVERSION`
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| 지표 | 설명 | 세분화 가능 | 데이터 유형 |
+| `conversion_purchases` | PURCHASE 유형의 전환 수와 해당 판매 금액 및 주문 수량 | `PLATFORMS`만 | JSON object |
+| `conversion_sign_ups` | SIGN\_UP 유형의 전환 수와 해당 판매 금액 및 주문 수량 | `PLATFORMS`만 | JSON object |
+| `conversion_site_visits` | SITE\_VISIT 유형의 전환 수와 해당 판매 금액 및 주문 수량 | `PLATFORMS`만 | JSON object |
+| `conversion_downloads` | DOWNLOAD 유형의 전환 수와 해당 판매 금액 및 주문 수량 | `PLATFORMS`만 | JSON object |
+| `conversion_custom` | CUSTOM 유형의 전환 수와 해당 판매 금액 및 주문 수량 | `PLATFORMS`만 | JSON object |
+
+#### `MOBILE_CONVERSION`
+
+모바일 전환 통계는 MACT가 활성화된 광고주 계정에서만 사용할 수 있습니다.
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| 지표 | 설명 | 세분화 가능 | 데이터 유형 |
+| `mobile_conversion_spent_credits` | SPENT\_CREDIT 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_installs` | INSTALL 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_content_views` | CONTENT\_VIEW 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_add_to_wishlists` | ADD\_TO\_WISHLIST 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_checkouts_initiated` | CHECKOUT\_INITIATED 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_reservations` | RESERVATION 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_tutorials_completed` | TUTORIAL\_COMPLETED 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_achievements_unlocked` | ACHIEVEMENT\_UNLOCKED 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_searches` | SEARCH 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_add_to_carts` | ADD\_TO\_CART 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_payment_info_additions` | PAYMENT\_INFO\_ADDITION 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_re_engages` | RE\_ENGAGE 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_shares` | SHARE 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_rates` | RATE 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_logins` | LOGIN 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_updates` | UPDATE 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_levels_achieved` | LEVEL\_ACHIEVED 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_invites` | INVITE 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| `mobile_conversion_key_page_views` | KEY\_PAGE\_VIEW 유형의 모바일 전환을 post\_view, post\_engagement로 분류 | ✔ | JSON object |
+| mobile\_conversion\_downloads | DOWNLOAD 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| mobile\_conversion\_purchases | PURCHASE 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| mobile\_conversion\_sign\_ups | SIGN\_UP 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+| mobile\_conversion\_site\_visits | SITE\_VISIT 유형의 모바일 전환을 post\_view, post\_engagement, assisted, order\_quantity, sale\_amount로 분류 | ✔ | JSON object |
+
+#### `LIFE_TIME_VALUE_MOBILE_CONVERSION`
+
+라이프타임 모바일 전환 통계는 MACT가 활성화된 광고주 계정에서만 사용할 수 있습니다.
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| 지표 | 설명 | 세분화 가능 | 데이터 유형 |
+| `mobile_conversion_lifetime_value_purchases` | PURCHASE 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_sign_ups` | SIGN\_UP 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_updates` | UPDATE 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_tutorials_completed` | TUTORIAL\_COMPLETED 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_reservations` | RESERVATION 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_add_to_carts` | ADD\_TO\_CART 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_add_to_wishlists` | ADD\_TO\_WISHLIST 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_checkouts_initiated` | CHECKOUT\_INITIATED 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_levels_achieved` | LEVEL\_ACHIEVED 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_achievements_unlocked` | ACHIEVEMENT\_UNLOCKED 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_shares` | SHARE 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_invites` | INVITE 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_payment_info_additions` | PAYMENT\_INFO\_ADDITION 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_spent_credits` | SPENT\_CREDIT 유형의 모바일 전환 분류 | | JSON object |
+| `mobile_conversion_lifetime_value_rates` | RATE 유형의 모바일 전환 분류 | | JSON object |
+
+### 세분화
+
+세분화 리포팅은 특정 타깃팅 유형의 값별로 분리된 지표를 가져올 수 있게 해줍니다. 세분화는 상당한 추가 복잡성 때문에 [비동기 분석 쿼리](/x-ads-api/analytics#asynchronous-analytics)에서만 사용할 수 있습니다.
+
+2026년 5월 기준으로 다음 세분화 유형만 활성화되어 있습니다. METROS는 Nielsen DMA 코드를 숫자 문자열로 반환합니다(819 = Seattle-Tacoma). METROS와 같은 지리적 세분화 유형은 country 파라미터가 필요합니다(미국의 경우 96683cc9126741d1).
+
+| | |
+| :-- | :-- |
+| 세분화 유형 | `country` 파라미터 필수 |
+| `AGE` | |
+| `GENDER` | |
+| `METROS` | ✔ |
+| `PLATFORMS` | |
+
+## 파생 지표
+
+캠페인 지표는 [캠페인 목표](/x-ads-api/campaign-management)에 따라 달라집니다. 이 가이드를 사용해 적용된 목표에 기반한 파생 지표 계산 방법을 확인하세요.
+
+중괄호 없이 표기된 `metric`은 Ads API [분석](/x-ads-api/analytics#synchronous-analytics) 엔드포인트에서 반환되는 지표입니다. `{curley brackets}`로 둘러싸인 이름은 해당 카테고리의 파생 지표를 나타냅니다.
+
+### ENGAGEMENTS
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `{Total Engagements}` | `promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements` 또는 `promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows` |
+| `{Engagement Rate}` | `{Total Engagements} / {Impressions}` |
+| `billed_charge_local_micro / {Total Engagements}` | |
+
+### WEBSITE\_CLICKS
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `{Link Clicks}` | `promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks` |
+| `{Click Rate}` | `{Link Clicks} / {Impressions}` |
+| `billed_charge_local_micro / {Link Clicks}` | |
+| `conversion_site_visits` | |
+| `{Conversion Rate}` | `conversion_site_visits / {Impressions}` |
+| `billed_charge_local_micro / conversion_site_visits` | |
+
+### APP\_INSTALLS
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `{App Clicks}` | `promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks` |
+| `{App Click Rate}` | `{App Clicks} / {Impressions}` |
+| `billed_charge_local_micro / {App Clicks}` | |
+| `billed_charge_local_micro / mobile_conversion_installs` | |
+
+### FOLLOWERS
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| `promoted_account_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `promoted_account_follows` | |
+| `{Follow Rate}` | `promoted_account_follow_rate` |
+| `billed_charge_local_micro / promoted_account_follows` | |
+
+### VIDEO\_VIEWS
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| | `billed_charge_local_micro / {Impressions} / 1000` |
+| `{Video Views}` | `promoted_video_total_views` |
+| `{Video Rate}` | `promoted_video_total_views / {Impressions}` |
+| `{Cost Per View}` | `billed_charge_local_micro / promoted_video_total_views` |
+
+### QUALIFIED\_IMPRESSIONS
+
+| | |
+| :-- | :-- |
+| 파생 지표 | 노출 지표 계산식 |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| | `billed_charge_local_micro / {Impressions} / 1000` |
+| `{Qualified Impressions}` | `promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions` |
+| `{Qualified Impression Rate}` | `{Qualified Impressions} / {Impressions}` |
+| `{Cost Per 1000 Qualified Impressions }` | `billed_charge_local_micro / {Qualified Impressions} / 1000` |
+
+### CUSTOM
+
+`PROMOTED_ACCOUNT`의 `placement_type`에 대해서는 위의 `FOLLOWERS` 목표를 참고하세요. 이 목표를 가진 그 외 모든 게재 위치에 대해서는 해당 파생 지표를 위해 `ENGAGEMENTS`를 참고하세요.
+
+## 가이드
+
+### Active Entities
+
+#### 소개
+
+[Active Entities 엔드포인트](/x-ads-api/analytics#get-stats-accounts-account-id-active-entities)는 [동기](/x-ads-api/analytics#get-stats-accounts-account-id) 및 [비동기](/x-ads-api/analytics#asynchronous-analytics) 분석 엔드포인트와 함께 사용되도록 설계되었습니다. 이 엔드포인트는 어떤 캠페인에 대해 분석을 요청해야 하는지에 대한 정보를 제공하기 때문입니다. 광고 엔티티와 해당 지표가 변경된 시점에 대한 상세 정보를 반환함으로써 이를 수행합니다. 이 엔드포인트를 사용하면 코드와 분석 가져오기 로직이 크게 단순해집니다.
+
+이 가이드는 엔드포인트와 그 데이터 소스에 대한 정보와 맥락을 포함합니다. 또한 분석 엔드포인트와 함께 Active Entities를 사용하는 방법을 보여주는 [사용 가이드라인](#usage)과 [예제 요청](#example)도 제공합니다. [요약 섹션](#summary)은 권장 접근 방식에 대한 고수준 설명을 제공합니다.
+
+#### 데이터
+
+광고 엔티티의 지표가 변경될 때마다 해당 변경에 대한 정보를 기록합니다. 이러한 변경 이벤트는 시간 단위 버킷에 저장되며, 엔티티에 대한 상세 정보와 변경이 적용되는 시각을 포함합니다. 후자가 필요한 이유는 변경 이벤트가 항상 기록 시점과 일치하지는 않기 때문입니다. 청구 조정이 흔한 이유 중 하나이지만, 그 외에도 다른 이유들이 있습니다.
+
+#### 엔드포인트
+
+### 요청
+
+Active Entities 요청은 광고 계정 범위 하에 있으며, 세 가지 필수 쿼리 파라미터(`entity`, `start_time`, `end_time`)를 갖습니다.
+
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2026-03-05T00:00:00Z&end_time=2026-03-06T00:00:00Z"`
+
+다음 `entity` 값이 지원됩니다: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET`. 이는 분석 엔드포인트가 지원하는 엔티티 유형을 반영합니다.
+
+`start_time` 및 `end_time` 값은 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)로 표현해야 하며 어떤 시간 단위 버킷을 쿼리할지 지정합니다. 이러한 값은 정시 단위로 표현해야 합니다.
+
+이 엔드포인트는 또한 결과를 필터링하는 데 사용할 수 있는 세 가지 선택적 파라미터(`funding_instrument_ids`, `campaign_ids`, `line_item_ids`)를 지원합니다. 이들은 광고 계층의 모든 수준 및 지정된 모든 `entity` 유형에서 작동합니다.
+
+### 응답
+
+위 요청에 대한 Active Entities 응답은 아래와 같습니다.
+
+```json
+ {
+ "request": {
+ "params": {
+ "account_id": "18ce54d4x5t",
+ "entity": "PROMOTED_TWEET",
+ "start_time": "2026-03-05T00:00:00Z",
+ "end_time": "2026-03-06T00:00:00Z"
+ }
+ },
+ "data": [
+ {
+ "entity_id": "2r0wxw",
+ "activity_start_time": "2026-03-04T20:55:20Z",
+ "activity_end_time": "2026-03-05T03:43:56Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ },
+ {
+ "entity_id": "2r30fn",
+ "activity_start_time": "2026-03-05T08:11:08Z",
+ "activity_end_time": "2026-03-05T14:40:59Z",
+ "placements": [
+ "ALL_ON_TWITTER",
+ "PUBLISHER_NETWORK"
+ ]
+ }
+ ]
+ }
+```
+
+`data` 배열은 후속 분석 요청에 포함시켜야 하는 모든 엔티티에 대한 객체를 포함합니다. 이 집합 외부의 ID에 대해 분석을 요청해서는 안 됩니다.
+
+각 객체는 `entity_id`, `activity_start_time`, `activity_end_time`, `placements`의 네 가지 필드를 포함합니다. activity 시작 및 종료 시각은 해당 엔티티의 변경 이벤트가 적용되는 기간을 나타내며, 따라서 후속 분석 요청에서 지정해야 할 날짜를 결정합니다. `placements` 배열에는 `ALL_ON_TWITTER`, `SPOTLIGHT`, `TREND` 값이 포함될 수 있습니다. 이는 주어진 엔티티 ID에 대해 어떤 게재 위치를 요청해야 하는지를 나타냅니다.
+
+#### 사용법
+
+Active Entities 엔드포인트는 분석 요청을 어떻게 만들지를 좌우해야 합니다. 다음 사용 가이드라인은 분석 동기화를 지원하기 위해 작성되었으며, 파트너가 자신의 데이터 저장소를 X와 동기화 상태로 유지할 수 있게 해줍니다. 다시 말해, 이는 정기적으로 예약된 백그라운드 동기화를 수행하는 방법을 설명합니다.
+
+개발자가 내려야 할 두 가지 결정이 있습니다.
+
+1. 얼마나 자주 active entities 정보를 요청할지, 따라서 얼마나 자주 분석을 가져올지.
+2. activity 시작 및 종료 시각을 사용해 분석 요청의 `start_time` 및 `end_time` 값을 어떻게 결정할지.
+
+이는 요약 다음의 두 하위 섹션에서 더 자세히 다룹니다.
+
+### 요약
+
+분석 요청을 어떻게 만들지를 좌우하기 위해 Active Entities 엔드포인트를 다음과 같이 사용하세요. 얼마나 자주 active entities 정보를 요청할지(따라서 얼마나 자주 분석을 가져올지)를 결정한 후에 이를 따르세요.
+
+1. Active Entities 요청을 보냅니다.
+2. 게재 위치별로 응답을 분할합니다. `ALL_ON_TWITTER` 그룹, `SPOTLIGHT` 그룹, `TREND` 그룹으로 나눕니다.
+3. 각 게재 위치 그룹에 대해 다음을 수행합니다.
+ 1. 엔티티 ID를 추출합니다.
+ 2. 분석 `start_time` 및 `end_time` 값을 결정합니다.
+ - 최소 `activity_start_time`을 찾습니다. 이 값을 내림합니다.
+ - 최대 `activity_end_time`을 찾습니다. 이 값을 올림합니다.
+ 3. 분석 요청(들)을 보냅니다.
+ - 엔티티 ID를 20개씩 배치로 묶습니다.
+ - #3b의 `start_time` 및 `end_time` 값을 사용합니다.
+ - 적절한 `placement` 값을 지정합니다.
+ 4. 데이터 저장소에 씁니다.
+
+Python SDK를 사용하는 예제로 [active\_entities.py](https://github.com/xdevplatform/twitter-python-ads-sdk/blob/master/examples/active_entities.py)를 참고하세요.
+
+### 빈도
+
+첫 번째 질문에 대한 답은 Active Entities 요청에서 사용해야 할 기간을 결정합니다. 예를 들어, 매 시간 active entities 정보를 요청한다면 기간은 1시간이어야 합니다. 하루에 한 번 active entities 정보를 요청한다면 기간은 하루여야 합니다. 다시 말해, 현재 요청의 `start_time`이 이전 요청의 `end_time`과 같도록 기간을 선택해야 합니다.
+
+
+ **참고**: 한 시간 창은 한 번만 요청해야 합니다. 동일한 시간 창을 두 번 이상 요청하면 불필요한 분석 요청이 발생합니다. (예외는 아래.)
+
+
+_현재_ 시간에 대해 한 시간에 여러 번 분석을 요청하려는 파트너의 경우 동일한 패턴이 적용됩니다. 즉, 빈도가 기간을 결정합니다. 아래 표는 이 시나리오에 대한 Active Entities 시작 및 종료 타임스탬프 예시를 보여줍니다.
+
+| | | |
+| :-- | :-- | :-- |
+| **요청 시각** | **`start_time` 타임스탬프** | **`end_time` 타임스탬프** |
+| 00:15:00 | 00:00:00 | 00:15:00 |
+| 00:30:00 | 00:15:00 | 00:30:00 |
+| 00:45:00 | 00:30:00 | 00:45:00 |
+| 01:00:00 | 00:45:00 | 01:00:00 |
+
+변경 이벤트가 저장되는 방식 때문에, 위의 네 Active Entities 요청은 모두 동일한 시간 단위 버킷을 쿼리하며, 이는 이 사용 사례에 필요합니다. 다만 현재 시간이 지난 후에는 이 시간 단위 버킷을 더 이상 쿼리해서는 안 됩니다.
+
+### Activity 시각
+
+activity 시작 및 종료 시각을 다룰 때 다음 접근 방식을 권장합니다. Active Entities 응답의 모든 객체에서 최소 `activity_start_time`과 최대 `activity_end_time`을 찾습니다. 이 값들을 수정하여 최소 activity 시작 시각은 내림하고 최대 activity 종료 시각은 올림합니다. 구체적으로, 다음 표에 나타난 것처럼 둘 다 타임스탬프를 0으로 설정하고 종료 시각에 하루를 더합니다. 이것이 후속 분석 요청에 지정되어야 할 시작 및 종료 시각입니다.
+
+| | |
+| :-- | :-- |
+| **최소, 최대 activity 시각** | **파생된 시각** |
+| 2026-03-04T20:55:20Z
2026-03-05T14:40:59Z | 2026-03-04T00:00:00Z
2026-03-06T00:00:00Z |
+
+**참고**: 시·분·초를 0으로 설정한 타임스탬프를 포함하는 것이 중요합니다. 그렇지 않고 날짜만 전달되면, 광고 계정의 시간대에서 자정에 시작하고 종료하는 분석을 요청하는 것으로 간주되며, 이는 원하는 결과가 아닐 수 있습니다. 예를 들어, 최소 activity 시작 시각이 2026-02-28T01:30:07Z이고 -08:00:00 오프셋을 가진 광고 계정에 대해 타임스탬프를 생략하면 분석 요청은 01:30과 08:00 사이에 발생한 변경 사항을 누락하게 됩니다.
+
+또는 전체 일자로 확장하지 않고 반환된 activity 기간에 대해서만 분석을 요청하고 싶다면 그렇게 할 수도 있습니다. 이 접근 방식을 사용하면 파생된 시작 및 종료 시각은 각각 2026-03-04T20:00:00Z와 2026-03-05T15:00:00Z가 됩니다. (이러한 범위는 분석 요청에서 `DAY` 그래뉼래리티를 지정한 경우에는 허용되지 않습니다.)
+
+#### 예제
+
+이 섹션은 동기 분석 엔드포인트와 함께 Active Entities를 사용하는 방법을 보여줍니다. (응답은 가독성을 위해 약간 수정되었습니다.) 이 예제에서는 Active Entities 엔드포인트가 매 시간 정각에 호출되며, 각 요청은 이전 시간을 살펴봅니다. 응답이 동기 분석 엔드포인트를 어떻게 사용할지를 결정합니다.
+
+첫 번째 Active Entities 요청은 03:00:00에 이루어집니다. 응답은 line item dvcz7의 지표가 변경되었으며, 해당 변경 이벤트가 02:02:55와 02:28:12 사이의 창에 적용됨을 나타냅니다.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T02:00:00Z&end_time=2026-02-11T03:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": [
+ {
+ "entity_id": "dvcz7",
+ "activity_start_time": "2026-02-11T02:02:55Z",
+ "activity_end_time": "2026-02-11T02:58:12Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ }
+ ]
+ }
+```
+
+위에서 설명한 접근 방식을 사용하여 이러한 activity 시작 및 종료 시각에 기반해 분석 `start_time`과 `end_time` 값은 각각 2026-02-11T00:00:00Z와 2026-02-12T00:00:00Z로 설정됩니다. active entities 정보에서 예상한 대로 아래의 각 지표 배열에서 세 번째 요소가 0이 아님을 확인할 수 있습니다.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
+```
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 24,
+ "data": [
+ {
+ "id": "dvcz7",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "engagements": [
+ 0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "video_total_views": [
+ 0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ]
+ }
+ }
+ ]
+ }
+ ],
+ "request": {}
+ }
+```
+
+다음 Active Entities 요청은 04:00:00에 이루어지며 이전 시간만 봅니다. 위에서 언급했듯이, 한 시간 창은 한 번만 요청해야 합니다. 응답을 보면 이 line item의 변경 이벤트가 02:00:00과 03:00:00 _둘 다_에 적용됨을 알 수 있습니다. 후속 분석 요청에서 두 시간 모두에 대한 변경 사항을 볼 것으로 예상됩니다.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T03:00:00Z&end_time=2026-02-11T04:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": [
+ {
+ "entity_id": "dvcz7",
+ "activity_start_time": "2026-02-11T02:07:17Z",
+ "activity_end_time": "2026-02-11T03:49:22Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ }
+ ]
+ }
+```
+
+03:00:00의 0이 아닌 지표를 보는 것 외에도, impressions, spend, MRC 비디오 조회가 이전 값에서 업데이트된 것을 볼 수 있습니다. 예를 들어, 02:00:00 시간의 impressions는 2,792에서 2,995로 증가했습니다. 이는 03:00:00 시간 동안 기록된 변경 이벤트가 02:00:00 시간에 어떻게 적용되는지를 보여줍니다.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
+```
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 24,
+ "data": [
+ {
+ "id": "dvcz7",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "engagements": [
+ 0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "video_total_views": [
+ 0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ]
+ }
+ }
+ ]
+ }
+ ],
+ "request": {}
+ }
+```
+
+05:00:00의 Active Entities 요청은 다시 이전 시간만 살펴보는데, 변경 이벤트가 03:00:00 시간에만 적용됨을 보여줍니다. 후속 요청에서 분석 지표의 변경 사항이 이를 반영합니다.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T04:00:00Z&end_time=2026-02-11T05:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": [
+ {
+ "entity_id": "dvcz7",
+ "activity_start_time": "2026-02-11T03:42:39Z",
+ "activity_end_time": "2026-02-11T03:48:48Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ }
+ ]
+ }
+```
+
+분석 응답은 03:00:00 시간의 지표만 변경되었음을 보여줍니다. 02:00:00 시간의 값은 이전 분석 요청과 동일합니다.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
+```
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 24,
+ "data": [
+ {
+ "id": "dvcz7",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "engagements": [
+ 0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "video_total_views": [
+ 0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ]
+ }
+ }
+ ]
+ }
+ ],
+ "request": {}
+ }
+```
+
+마지막으로, 06:00:00에는 추가 변경 이벤트가 없음을 확인합니다. **참고**: 다만 이것이 향후 이 line item에 대한 지표가 변경될 수 없음을 _의미하지는_ 않습니다.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T05:00:00Z&end_time=2026-02-11T06:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": []
+ }
+```
+
+### 비동기 가이드
+
+## API 레퍼런스
+
+### 비동기 분석
+
+#### 소개
+
+비동기 분석 엔드포인트는 파트너와 광고주가 서버가 비동기적으로 처리하는 생성 요청을 제출하여 지표를 요청할 수 있게 해줍니다. (이를 비동기 분석 "작업(job)"이라고 부릅니다.) 이 접근 방식을 사용하면 요청이 완료될 때까지 클라이언트의 연결을 유지하지 않아도 됩니다.
+
+이러한 엔드포인트는 동기 엔드포인트와 마찬가지로 파트너와 광고주가 캠페인 성과에 대한 상세 통계를 요청할 수 있게 해줍니다. accounts, funding instruments, campaigns, line items, promoted posts, media creatives에 대한 데이터를 요청하는 것을 지원합니다. 동기 엔드포인트와의 차이점은 비동기 분석 엔드포인트가 최대 90일까지의 더 긴 기간과 세분화를 지원한다는 점입니다. 둘 사이의 차이에 대한 추가 세부 사항은 [분석 개요](/x-ads-api/analytics) 페이지에서 확인할 수 있습니다.
+
+동기 엔드포인트와 달리 속도 제한은 주어진 계정에 대한 동시 작업 수에 기반합니다. 다시 말해, 특정 시점에 처리 중 상태에 있을 수 있는 작업 수에 기반합니다. 이는 광고 계정 수준에서 계산됩니다.
+
+#### 사용법
+
+비동기 분석 엔드포인트를 사용해 캠페인 지표를 가져오는 것은 여러 단계로 진행되는 과정입니다. 작업을 생성하고, 작업이 처리 완료되었는지 확인한 다음, 마지막으로 데이터를 다운로드하는 과정이 포함됩니다. 데이터 파일은 압축 해제해야 합니다. 네 가지 구체적인 단계는 아래에 요약되어 있습니다.
+
+1. [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) 엔드포인트를 사용해 작업을 생성합니다.
+2. [GET stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) 엔드포인트에 정기적인 간격으로 요청을 보내 작업이 처리 완료되었는지 확인합니다.
+3. 작업이 처리 완료되면 데이터 파일을 다운로드합니다.
+4. 데이터 파일의 압축을 풉니다.
+
+데이터 파일에서 반환된 응답 객체는 동기 분석 엔드포인트의 응답과 동일한 JSON 스키마를 갖습니다.
+
+세분화된 캠페인 지표는 비동기 분석 엔드포인트를 통해서만 사용할 수 있습니다. 캠페인 지표는 위치, 성별, 관심사, 키워드 등으로 분류될 수 있습니다. 전체 옵션 목록은 [지표 및 세분화](/x-ads-api/analytics#metrics-and-segmentation) 페이지를 참고하세요. 세분화된 지표를 요청하려면 작업을 생성할 때 `segmentation_type` 요청 파라미터를 사용하세요.
+
+#### 예제
+
+이 섹션은 비동기 분석 엔드포인트를 사용하는 방법을 보여줍니다.
+
+먼저 [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) 엔드포인트를 사용해 작업을 생성합니다. 아래 예제는 특정 line item에 대해 한 주 동안의 인게이지먼트 지표—노출 수, 좋아요, 클릭 수 등—를 요청합니다. (요청한 기간은 3월 20일을 포함하지 않으며, 타임스탬프가 자정으로 설정되어 있으므로 그 전까지만 포함됩니다.)
+
+```text
+$ twurl -X POST -H ads-api.x.com "/12/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2026-03-12T00:00:00Z&end_time=2026-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"
+```
+
+```json
+ {
+ "request": {
+ "params": {
+ "start_time": "2026-03-12T00:00:00Z",
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "placement": "ALL_ON_TWITTER",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ },
+ "data": {
+ "start_time": "2026-03-12T00:00:00Z",
+ "segmentation_type": null,
+ "url": null,
+ "id_str": "1120829647711653888",
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "id": 1120829647711653888,
+ "expires_at": null,
+ "account_id": "18ce54d4x5t",
+ "status": "PROCESSING",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "created_at": "2026-04-01T23:19:46Z",
+ "platform": null,
+ "updated_at": "2026-04-01T23:19:46Z",
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ }
+```
+
+이 응답은 line item 지표를 반환하지 않습니다. 방금 생성한 작업에 대한 정보만 제공합니다. 작업의 상태를 확인하려면 작업 ID가 필요합니다. 이는 응답 속성의 `id`와 `id_str` 모두에 표시됩니다.
+
+다음으로, 이전 응답의 `id_str`을 사용해 생성한 작업이 처리 완료되었는지 확인하고 싶을 것입니다. 이는 응답에 `"status": "SUCCESS"`로 표시됩니다. 이는 데이터를 다운로드할 준비가 되었음을 의미합니다. `url` 필드에는 다운로드 링크가 포함되어 있습니다.
+
+```text
+$ twurl -H ads-api.x.com "/12/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"
+```
+
+```json
+ {
+ "request": {
+ "params": {
+ "job_ids": [
+ 1120829647711653888
+ ]
+ }
+ },
+ "next_cursor": "1120828505715920896",
+ "data": [
+ {
+ "start_time": "2026-03-12T00:00:00Z",
+ "segmentation_type": null,
+ "url": "https://ton.twimg.com/advertiser-api-async-analytics/stats_job_1120829647711653888.json.gz",
+ "id_str": "1120829647711653888",
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "id": 1120829647711653888,
+ "expires_at": "2026-04-03T23:19:48Z",
+ "account_id": "18ce54d4x5t",
+ "status": "SUCCESS",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "created_at": "2026-04-01T23:19:46Z",
+ "platform": null,
+ "updated_at": "2026-04-01T23:19:48Z",
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ ]
+ }
+```
+
+위 예제에서는 단일 작업 ID를 전달하지만, 실제로는 최대 200개의 작업 ID를 지정하여 `job_ids` 파라미터로 여러 작업의 상태를 한 번에 확인하고 싶을 것입니다.
+
+다음으로, 표시된 `url` 값을 사용해 데이터 파일을 다운로드합니다.
+
+```text
+ $ wget https://ton.twimg.com/advertiser-api-async-analytics/stats_job_1120829647711653888.json.gz
+```
+
+마지막으로, 데이터 파일의 압축을 풉니다.
+
+```text
+`$ gunzip stats_job_1120829647711653888.json.gz`
+```
+
+파일의 내용은 아래와 같습니다.
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 1,
+ "data": [
+ {
+ "id": "el32n",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 3482
+ ],
+ "tweets_send": null,
+ "qualified_impressions": null,
+ "follows": null,
+ "app_clicks": null,
+ "retweets": [
+ 102
+ ],
+ "unfollows": null,
+ "likes": [
+ 15
+ ],
+ "engagements": [
+ 171
+ ],
+ "clicks": [
+ 30
+ ],
+ "card_engagements": null,
+ "poll_card_vote": null,
+ "replies": null,
+ "carousel_swipes": null
+ }
+ }
+ ]
+ }
+ ],
+ "request": {
+ "params": {
+ "start_time": "2026-03-12T00:00:00Z",
+ "segmentation_type": null,
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "platform": null,
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ }
+ }
+```
+
+### Reach 및 Average Frequency
+
+
+
+#### GET stats/accounts/:account\_id/reach/campaigns
+
+지정된 캠페인의 reach 및 average frequency 분석을 가져옵니다.
+
+### 리소스 URL
+
+`https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns`
+
+### 파라미터
+
+| 이름 | 설명 |
+| :-- | :-- |
+| account\_id _필수_ | 사용 중인 계정의 식별자입니다. 리소스 경로 내에 표시되며 일반적으로 [GET accounts](/x-ads-api/campaign-management/reference#accounts)를 제외한 모든 Advertiser API 요청에 필수 파라미터입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
Type: string
Example: `18ce54d4x5t` |
+| campaign\_ids _필수_ | 쉼표로 구분된 식별자 목록을 지정하여 원하는 캠페인으로만 응답 범위를 좁힙니다. 최대 20개의 ID를 제공할 수 있습니다.
**참고**: 최대 20개의 campaign ID를 제공할 수 있습니다.
Type: string
Example: `8fgzf` |
+| end\_time _필수_ | 가져올 데이터의 범위를 지정된 종료 시각으로 좁히며, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)로 표현합니다.
**참고**: 정시 단위(0분 0초)로 표현해야 합니다.
Type: string
Example: `2026-05-26T07:00:00Z` |
+| start\_time _필수_ | 가져올 데이터의 범위를 지정된 시작 시각으로 좁히며, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)로 표현합니다.
**참고**: 정시 단위(0분 0초)로 표현해야 합니다.
Type: string
Example: `2026-05-19T07:00:00Z` |
+
+### 요청 예시
+
+`GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2026-05-19&end_time=2026-05-26`
+
+### 응답 예시
+
+```json
+ {
+ "request": {
+ "params": {
+ "campaign_ids": [
+ "8fgzf"
+ ],
+ "start_time": "2026-05-19T00:00:00Z",
+ "end_time": "2026-05-26T00:00:00Z",
+ "account_id": "18ce54d4x5t"
+ }
+ },
+ "data_type": "reach",
+ "data": [
+ {
+ "id": "8fgzf",
+ "total_audience_reach": 1217,
+ "average_frequency": 1.01
+ }
+ ]
+ }
+```
+
+#### GET stats/accounts/:account\_id/reach/funding\_instruments
+
+지정된 funding instrument의 reach 및 average frequency 분석을 가져옵니다.
+
+### 리소스 URL
+
+`https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments`
+
+### 파라미터
+
+| 이름 | 설명 |
+| :-- | :-- |
+| account\_id _필수_ | 사용 중인 계정의 식별자입니다. 리소스 경로 내에 표시되며 일반적으로 [GET accounts](/x-ads-api/campaign-management/reference#accounts)를 제외한 모든 Advertiser API 요청에 필수 파라미터입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
Type: string
Example: `18ce54d4x5t` |
+| funding\_instrument\_ids _필수_ | 쉼표로 구분된 식별자 목록을 지정하여 원하는 funding instrument로만 응답 범위를 좁힙니다. 최대 20개의 ID를 제공할 수 있습니다.
**참고**: 최대 20개의 funding instrument ID를 제공할 수 있습니다.
Type: string
Example: `lygyi` |
+| end\_time _필수_ | 가져올 데이터의 범위를 지정된 종료 시각으로 좁히며, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)로 표현합니다.
**참고**: 정시 단위(0분 0초)로 표현해야 합니다.
Type: string
Example: `2026-05-26T07:00:00Z` |
+| start\_time _필수_ | 가져올 데이터의 범위를 지정된 시작 시각으로 좁히며, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)로 표현합니다.
**참고**: 정시 단위(0분 0초)로 표현해야 합니다.
Type: string
Example: `2026-05-19T07:00:00Z` |
+
+### 요청 예시
+
+```text
+GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2026-05-19&end_time=2026-05-26
+```
+
+### 응답 예시
+
+```json
+ {
+ "request": {
+ "params": {
+ "funding_instrument_ids": [
+ "lygyi"
+ ],
+ "start_time": "2026-05-19T00:00:00Z",
+ "end_time": "2026-05-26T00:00:00Z",
+ "account_id": "18ce54d4x5t"
+ }
+ },
+ "data_type": "reach",
+ "data": [
+ {
+ "id": "lygyi",
+ "total_audience_reach": 1217,
+ "average_frequency": 1.01
+ }
+ ]
+ }
+```
+
+### 동기 분석
+
+
+
+#### GET stats/accounts/:account\_id
+
+현재 계정에 대한 동기 분석을 가져옵니다. 최대 기간(`end_time` - `start_time`)은 7일까지 허용됩니다.
+
+### 리소스 URL
+
+`https://ads-api.x.com/12/stats/accounts/:account_id`
+
+### 파라미터
+
+| 이름 | 설명 |
+| :-- | :-- |
+| account\_id _필수_ | 사용 중인 계정의 식별자입니다. 리소스 경로 내에 표시되며 일반적으로 [GET accounts](/x-ads-api/campaign-management/reference#accounts)를 제외한 모든 Advertiser API 요청에 필수 파라미터입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
Type: string
Example: `18ce54d4x5t` |
+| end\_time _필수_ | 가져올 데이터의 범위를 지정된 종료 시각으로 좁히며, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)로 표현합니다.
Possible values: `ACCOUNT`, `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET` |
+| entity\_ids _필수_ | 데이터를 가져올 특정 엔티티입니다. 쉼표로 구분된 엔티티 ID 목록을 지정하세요.
Possible values: `DAY`, `HOUR`, `TOTAL` |
+| metric\_groups _필수_ | 반환되어야 하는 특정 지표입니다. 쉼표로 구분된 지표 그룹 목록을 지정하세요. 자세한 내용은 [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation)을 참고하세요.
**참고**: `MOBILE_CONVERSION` 데이터는 별도로 요청해야 합니다.
Type: enum
Possible values: `BILLING`, `ENGAGEMENT`, `LIFE_TIME_VALUE_MOBILE_CONVERSION`, `MOBILE_CONVERSION`, `VIDEO`, `WEB_CONVERSION` |
+| placement _필수_ | 가져올 데이터의 범위를 특정 게재 위치로 좁힙니다.
**참고**: 요청당 단일 값만 허용됩니다. X와 X Audience Platform 양쪽에 게재 위치를 가진 엔티티의 경우, 게재 위치 값마다 별도의 요청이 필요합니다.
Type: enum
Possible values: `ALL_ON_TWITTER`, `SPOTLIGHT`, `TREND` |
+| start\_time _필수_ | 가져올 데이터의 범위를 지정된 시작 시각으로 좁히며, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)로 표현합니다.
**참고**: 정시 단위(0분 0초)로 표현해야 합니다.
Type: string
Example: `2026-05-19T07:00:00Z` |
+
+### 요청 예시
+
+```text
+GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2026-05-19&end_time=2026-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT
+```
+
+### 응답 예시
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 1,
+ "data": [
+ {
+ "id": "8u94t",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 1233
+ ],
+ "tweets_send": null,
+ "qualified_impressions": null,
+ "follows": null,
+ "app_clicks": null,
+ "retweets": null,
+ "likes": [
+ 1
+ ],
+ "engagements": [
+ 58
+ ],
+ "clicks": [
+ 58
+ ],
+ "card_engagements": null,
+ "poll_card_vote": null,
+ "replies": null,
+ "carousel_swipes": null
+ }
+ }
+ ]
+ }
+ ],
+ "request": {
+ "params": {
+ "start_time": "2026-05-19T07:00:00Z",
+ "segmentation_type": null,
+ "entity_ids": [
+ "8u94t"
+ ],
+ "end_time": "2026-05-26T07:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "platform": null,
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ }
+ }
+```
+
+### Active Entities
+
+
+
+#### GET stats/accounts/:account\_id/active\_entities
+
+지정된 기간에 분석 지표가 변경된 엔티티에 대한 상세 정보를 가져옵니다.
+
+이 엔드포인트는 분석 엔드포인트와 함께 사용해야 합니다. 이 엔드포인트의 결과는 어떤 광고 엔티티에 대해 분석을 요청해야 하는지를 나타냅니다. 사용 가이드라인은 [Active Entities 가이드](/x-ads-api/analytics#active-entities)를 참고하세요.
+
+변경 이벤트는 시간 단위 버킷에서 사용할 수 있습니다.
+
+- `start_time` 및 `end_time` 값은 쿼리할 시간 단위 버킷을 지정합니다.
+- 반환된 `data` 배열에는 후속 분석 요청에 포함시켜야 하는 모든 엔티티에 대한 객체가 포함됩니다.
+- **중요**: 후속 분석 요청에서 지정해야 할 날짜는 `activity_start_time` 및 `activity_end_time` 값을 기반으로 결정되어야 합니다.
+ - 이 값들은 저장된 변경 이벤트가 _적용되는_ 기간을 나타냅니다. 엔티티별로 반환됩니다.
+
+**참고**: 최대 기간(`end_time` - `start_time`)은 90일까지 허용됩니다.
+
+### 리소스 URL
+
+`https://ads-api.x.com/12/stats/accounts/:account_id/active_entities`
+
+### 파라미터
+
+| 이름 | 설명 |
+| :-- | :-- |
+| account\_id _필수_ | 사용 중인 계정의 식별자입니다. 리소스 경로 내에 표시되며 일반적으로 [GET accounts](/x-ads-api/campaign-management/reference#accounts)를 제외한 모든 Advertiser API 요청에 필수 파라미터입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다.
Type: string
Example: `18ce54d4x5t` |
+| end\_time _필수_ | 가져올 데이터의 범위를 지정된 종료 시각으로 좁히며, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)로 표현합니다.
Possible values: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET` |
+| start\_time _필수_ | 가져올 데이터의 범위를 지정된 시작 시각으로 좁히며, [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)로 표현합니다.
**참고**: 정시 단위(0분 0초)로 표현해야 합니다.
Type: string
Example: `2026-05-19T07:00:00Z` |
+| campaign\_ids _선택_ | 쉼표로 구분된 식별자 목록을 지정하여 원하는 캠페인과 관련된 엔티티로만 응답 범위를 좁힙니다. 최대 200개의 ID를 제공할 수 있습니다.
**참고**: `funding_instrument_ids` 및 `line_item_ids`와 함께 사용할 수 없습니다.
Type: string
Example: `8wku2` |
+| funding\_instrument\_ids _선택_ | 쉼표로 구분된 식별자 목록을 지정하여 원하는 funding instrument와 관련된 엔티티로만 응답 범위를 좁힙니다. 최대 200개의 ID를 제공할 수 있습니다.
**참고**: `campaign_ids` 및 `line_item_ids`와 함께 사용할 수 없습니다.
Type: string
Example: `lygyi` |
+| line\_item\_ids _선택_ | 쉼표로 구분된 식별자 목록을 지정하여 원하는 line item과 관련된 엔티티로만 응답 범위를 좁힙니다. 최대 200개의 ID를 제공할 수 있습니다.
**참고**: `campaign_ids` 및 `line_item_ids`와 함께 사용할 수 없습니다.
Type: string
Example: `8v7jo` |
+
+### 요청 예시
+
+`GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2026-02-28&end_time=2026-03-01`
+
+### 응답 예시
+
+```json
+ {
+ "request": {
+ "params": {
+ "account_id": "18ce54d4x5t",
+ "entity": "PROMOTED_TWEET",
+ "start_time": "2026-02-28T08:00:00Z",
+ "end_time": "2026-03-01T08:00:00Z"
+ }
+ },
+ "data": [
+ {
+ "entity_id": "2mvb28",
+ "activity_start_time": "2026-02-28T01:30:07Z",
+ "activity_end_time": "2026-03-01T07:42:55Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ },
+ {
+ "entity_id": "2mvb29",
+ "activity_start_time": "2026-02-27T11:30:07Z",
+ "activity_end_time": "2026-03-01T07:42:50Z",
+ "placements": [
+ "ALL_ON_TWITTER",
+ "PUBLISHER_NETWORK"
+ ]
+ },
+ {
+ "entity_id": "2mvfan",
+ "activity_start_time": "2026-02-27T09:00:05Z",
+ "activity_end_time": "2026-03-01T06:06:36Z",
+ "placements": [
+ "PUBLISHER_NETWORK"
+ ]
+ },
+ {
+ "entity_id": "2n17dx",
+ "activity_start_time": "2026-02-28T02:02:26Z",
+ "activity_end_time": "2026-03-01T07:52:44Z",
+ "placements": [
+ "ALL_ON_TWITTER",
+ "PUBLISHER_NETWORK"
+ ]
+ }
+ ]
+ }
+```
diff --git a/pt/x-ads-api/analytics.mdx b/pt/x-ads-api/analytics.mdx
new file mode 100644
index 000000000..43ace7547
--- /dev/null
+++ b/pt/x-ads-api/analytics.mdx
@@ -0,0 +1,1263 @@
+---
+title: "Analytics"
+keywords: ["analytics de publicidade", "analytics de anúncios", "analytics de campanha", "métricas de anúncios", "métricas de publicidade", "desempenho de campanha"]
+description: "Obtenha métricas de desempenho de campanhas na X Ads API usando endpoints síncronos e assíncronos de analytics, com opções de segmentação e granularidade."
+---
+
+As métricas de analytics ajudam parceiros e anunciantes a entender o desempenho do conteúdo que promovem na X. Isso inclui informações como impressões, cliques, visualizações de vídeo e gastos. Além disso, parceiros e anunciantes podem obter métricas detalhadas para diversos segmentos das audiências que alcançam.
+
+A Ads API oferece duas formas de obter métricas detalhadas de desempenho de campanha: de modo síncrono e de modo assíncrono. Com chamadas síncronas de analytics, as métricas solicitadas são retornadas na própria resposta. Com os endpoints assíncronos de analytics, as métricas solicitadas ficam disponíveis em um arquivo de resultados para download depois que o "job" associado termina de processar. O endpoint síncrono suporta intervalos de tempo curtos e é ideal para otimizações de campanha em tempo real. Os endpoints assíncronos suportam intervalos de tempo muito maiores e, portanto, são indicados para buscar volumes muito maiores de dados, ideais para gerar relatórios ou backfills históricos.
+
+## Detalhes
+
+### Síncrono vs. Assíncrono
+
+As diferenças entre os endpoints síncrono e assíncrono de analytics estão resumidas na tabela a seguir. Essas informações têm como objetivo ajudar os desenvolvedores a escolher qual conjunto de endpoints utilizar.
+
+| Recurso | Síncrono | Assíncrono |
+| :-- | :-- | :-- |
+| Rate limiting | Em nível de usuário: 250 requisições / 15 minutos | Em nível de conta: 100 jobs simultâneos\* |
+| Intervalo de tempo | 7 dias | 90 dias (não segmentado) 45 dias (segmentado) |
+| Segmentação | Não | Sim |
+| Retorno da resposta | Dados de métricas | Estado de processamento do job\*\* |
+| Caso de uso recomendado | Otimização em tempo real Requisições de interface de usuário | Sincronizações regulares agendadas Backfill de dados históricos |
+
+
+ \* Refere-se ao número máximo de jobs que podem estar em estado de processamento a qualquer momento.
+
+ \*\* Quando o job termina de processar com sucesso, uma URL é retornada. É a partir dela que o arquivo de resultados compactado (gzip) pode ser baixado.
+
+ Fora isso, os endpoints oferecem a mesma funcionalidade.
+
+
+### Casos de uso
+
+Existem três principais casos de uso de analytics.
+
+1. Otimização em tempo real: usar métricas de desempenho para atualizar campanhas ativas
+2. Sincronização: sincronizações regulares agendadas em segundo plano
+3. Onboarding de nova conta: backfill de dados históricos
+
+O endpoint síncrono de analytics pode ser usado para otimização em tempo real, a fim de atualizar campanhas com base em mudanças nas métricas nos últimos 5 a 15 minutos. Qualquer um dos endpoints pode ser usado para sincronização de analytics. Lembre-se de que o intervalo de tempo desejado e a necessidade ou não de segmentação determinarão qual endpoint usar. O onboarding de novas contas deve ser feito apenas com os endpoints assíncronos de analytics. (O endpoint síncrono de analytics nunca deve ser usado para obter grandes volumes de dados.)
+
+Os endpoints assíncronos de analytics podem alimentar dashboards e outros elementos de UI, desde que as métricas sejam sincronizadas por meio de um processo no backend. Sua implementação deve evitar chamar os endpoints assíncronos de analytics para atender a requisições de interface de usuário.
+
+### Opções de requisição
+
+As requisições de analytics têm escopo nas contas de anúncios e, portanto, exigem o ID da conta no caminho do recurso. As opções da requisição, listadas a seguir, são especificadas como parâmetros de query. Os seguintes tipos de valores são obrigatórios.
+
+- Entidades: o tipo de entidade, bem como até 20 IDs de entidades para os quais você deseja obter analytics
+- Intervalo de tempo: os horários de início e fim, expressos em ISO 8601
+ - **Observação:** devem ser expressos em horas inteiras
+- Grupos de métricas: um ou mais conjuntos de métricas relacionadas (consulte Métricas e Segmentação para ver a lista de métricas dentro de cada grupo)
+- Granularidade: especifica o nível de agregação em que as métricas devem ser retornadas
+- Placement: determina se as métricas são obtidas para anúncios servidos na X ou fora dela
+ - **Observação:** apenas um único valor de placement pode ser especificado por requisição
+
+Use os parâmetros `start_time` e `end_time` para especificar um intervalo de tempo. Esses valores devem estar alinhados com a granularidade especificada da seguinte forma.
+
+1. `TOTAL`: especifique qualquer intervalo de tempo (dentro dos limites do endpoint)
+2. `DAY`: tanto o horário de início quanto o de fim devem estar alinhados com a meia-noite no fuso horário da conta
+3. `HOUR`: especifique qualquer intervalo de tempo (dentro dos limites do endpoint)
+
+O horário de fim é exclusivo. Por exemplo, uma requisição com `start_time=2026-01-01T00:00:00Z` e `end_time=2026-01-02T00:00:00Z` retornará o equivalente a um único dia de métricas de analytics (não dois), pois esse intervalo cobre apenas um período de 24 horas.
+
+**Segmentação**
+
+Disponível apenas através dos endpoints assíncronos de analytics, a segmentação permite que parceiros e anunciantes obtenham métricas divididas por valores específicos de segmentação (targeting). Para solicitar métricas segmentadas, use o parâmetro `segmentation_type`. Para mais detalhes sobre as opções de segmentação, consulte [Métricas e Segmentação](/x-ads-api/analytics#metrics-and-segmentation).
+
+## Perguntas frequentes
+
+Por que os números da Ads API não batem com os exibidos na UI do X Ads?
+
+- Certifique-se de ter solicitado dados para todos os placements: `ALL_ON_TWITTER`, `SPOTLIGHT` e `TREND`.
+- Lembre-se de que os horários de fim na Ads API são exclusivos; na UI de Ads, são inclusivos.
+
+Por que os números mudam dependendo de quando solicito os dados?
+
+- Assim que as métricas de relatório ficam disponíveis, você pode obtê-las. Elas ficam disponíveis em tempo quase real. Esses resultados iniciais, porém, são estimativas e, portanto, podem mudar. As métricas são finalizadas após 24 horas, com exceção dos dados de gastos.
+- As métricas de gasto geralmente são finais em até 3 dias após o evento. No entanto, processamos dados de cobrança por até 14 dias a partir da data do evento (para filtragem de spam, por exemplo).
+
+Como posso determinar quais IDs de entidade solicitar para um período específico?
+
+- Use o [endpoint Active Entities](/x-ads-api/analytics#active-entities-2)
+
+Por que todos os valores na resposta de analytics são `null`?
+
+- É provável que a campanha não tenha sido veiculada durante o período solicitado
+- Use o [endpoint Active Entities](/x-ads-api/analytics#active-entities-2) para determinar quais entidades buscar e em qual período
+
+Por que a API exibe valores `null` enquanto a UI exibe 0?
+
+- A UI opta por exibir esses valores como 0, mas os valores são equivalentes
+
+Como posso solicitar métricas associadas a um placement granular, como a timeline do X?
+
+- Suportamos os seguintes valores de placement em analytics: `ALL_ON_TWITTER`, `SPOTLIGHT` e `TREND`
+
+É possível obter métricas para entidades deletadas ou pausadas?
+
+- Sim. O status da entidade não afeta a disponibilidade das métricas de analytics.
+
+Por que os valores segmentados não batem com os não segmentados?
+
+- Os dados segmentados _não_ devem somar 100% aos dados não segmentados, devido à forma como essas informações são derivadas.
+
+Por que os valores segmentados da API não batem com o que o Ads Manager UI exibe?
+
+- A API retorna métricas segmentadas com escopo no tipo de entidade específico que você consulta (CAMPAIGN, PROMOTED\_TWEET). A UI do Ads Manager agrega os dados entre os tipos de entidade. Essas são visões diferentes dos mesmos dados subjacentes e esse é o comportamento esperado.
+
+É possível solicitar dados segmentados por múltiplas dimensões?
+
+- Não suportamos multi-segmentação.
+
+## Boas práticas
+
+Algumas boas práticas ao coletar dados de [analytics](/x-ads-api/analytics) da Ads API.
+
+### Rate Limiting e Retries
+
+- Em queries com rate limit atingido (que retornam status `HTTP 429`), você deve inspecionar o header `x-rate-limit-reset` e tentar novamente apenas no horário indicado ou após ele.
+- Em queries que resultem em status HTTP 503 Service Unavailable, você deve inspecionar o header `retry-after` e tentar novamente apenas após o horário indicado.
+- Aplicações que não respeitarem os horários indicados para retries podem ter o acesso à Ads API revogado ou limitado sem aviso prévio.
+
+### Métricas de Analytics em poucas palavras
+
+- Todas as métricas de analytics ficam travadas e não mudam após 24 horas, com exceção de `billed_charge_local_micro`.
+- A métrica `billed_charge_local_micro` é uma estimativa por até 3 dias após o retorno do dado.
+- Após 24 horas, essa métrica pode diminuir devido a créditos por overspend (anúncios servidos após o `end_time` informado) e por eventos cobráveis identificados como spam. Essa métrica muda minimamente após 24 horas.
+- Consulte [Analytics](/x-ads-api/analytics) para mais informações.
+
+### Obtendo dados em tempo real e não segmentados
+
+- Sempre forneça tanto `start_time` quanto `end_time`.
+- Não busque dados para entidades com mais de 7 dias.
+- Solicite os dados (idealmente) com granularidade `HOUR`, pois você sempre pode agregar e somar para obter granularidade `DAY` e `TOTAL`.
+- Solicite dados (idealmente) no nível de `line_items` e `promoted_tweets`, pois sempre é possível agregar e somar essas métricas para obter totais em toda a hierarquia de entidades de anúncios (ou seja, nos níveis de campaign, funding instrument ou account).
+- Salve e armazene os valores das métricas de analytics do seu lado (localmente).
+- Não consulte repetidamente dados com mais de 30 dias. Esses dados não mudarão e devem ser armazenados localmente.
+- Todos os dados não segmentados são em tempo real e devem estar disponíveis em segundos após a ocorrência de um evento.
+- Agrupe métricas de conversão e métricas que não são de conversão em requisições separadas.
+
+### Obtendo dados segmentados
+
+- Consulte as diretrizes fornecidas em "Obtendo dados em tempo real e não segmentados" acima. Recomendações adicionais abaixo.
+- Para a maioria dos tipos de dados segmentados, é possível que os dados não estejam completos por até 1 hora em alguns casos. Dados segmentados por `INTERESTS` podem ter atraso de até 12 horas.
+- Os dados segmentados não devem somar 100% aos dados não segmentados, devido à forma como essas informações são derivadas.
+
+### Obtendo dados históricos
+
+- Ao fazer backfill de dados (por exemplo, ao adicionar uma nova conta de anunciante), você pode precisar fazer várias requisições com janelas menores de `start_time` e `end_time`.
+- Limite suas buscas a janelas de até 30 dias.
+- Faça throttling dessas requisições e distribua-as ao longo do tempo para não esgotar seus rate limits.
+
+### Exemplo
+
+Você encontra um script de exemplo demonstrando algumas dessas boas práticas (`fetch_stats`) em nosso repositório [ads-platform-tools no GitHub](https://github.com/xdevplatform/ads-platform-tools).
+
+## Métricas por objetivo
+
+Quais métricas são aplicáveis a uma entidade depende do [objetivo da campanha](/x-ads-api/campaign-management). Use este guia para determinar os grupos de métricas relevantes a buscar para cada tipo de objetivo, bem como a forma como métricas derivadas adicionais podem ser calculadas.
+
+### `ENGAGEMENTS`
+
+**Grupos de métricas relevantes:**`ENGAGEMENT` e `BILLING`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| Engagement Rate | `engagements/impressions` |
+| CPE | `billed_charge_local_micro/engagements` |
+
+### `WEBSITE_CLICKS` e `WEBSITE_CONVERSIONS`
+
+**Grupos de métricas relevantes:**`ENGAGEMENT`, `BILLING` e `WEB_CONVERSION`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Click Rate | `clicks/impressions` |
+| CPLC | `billed_charge_local_micro/clicks` |
+| Total Conversions | `conversion_custom` \+ `conversion_site_visits` \+ `conversion_sign_ups` \+ `conversion_downloads` \+ `conversion_purchases` |
+| Conversion Rate | Total Conversions / `impressions` |
+| CPA | `billed_charge_local_micro` / Total Conversions |
+
+### `APP_INSTALLS`
+
+**Grupos de métricas relevantes:**`ENGAGEMENT`, `BILLING`, `MOBILE_CONVERSION` e `LIFE_TIME_VALUE_MOBILE_CONVERSION`. `VIDEO` também é aplicável se o video app card for usado nos criativos.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| App Click Rate | `app_clicks/impressions` |
+| CPAC | `billed_charge_local_micro/app_clicks` |
+| CPI | `billed_charge_local_micro/mobile_conversion_installs` |
+
+### `FOLLOWERS`
+
+**Grupos de métricas relevantes:**`ENGAGEMENT` e `BILLING`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Follow Rate | `follows/impressions` |
+| CPF | `billed_charge_local_micro/follows` |
+
+### `VIDEO_VIEWS`
+
+**Grupos de métricas relevantes:**`ENGAGEMENT`, `BILLING` e `VIDEO`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Video Rate | `video_total_views/impressions` |
+| Cost Per View | `billed_charge_local_micro/video_total_views` |
+
+### `VIDEO_VIEWS_PREROLL`
+
+**Grupos de métricas relevantes:**`ENGAGEMENT`, `BILLING` e `VIDEO`.
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| CPM | `billed_charge_local_micro/impressions/1000` |
+| Video Rate | `video_total_views/impressions` |
+| Cost Per View | `billed_charge_local_micro/video_total_views` |
+
+## Métricas e Segmentação
+
+Este documento é uma visão geral das métricas disponíveis em nosso [Analytics](/x-ads-api/analytics) para cada tipo de entidade, bem como das segmentações disponíveis para cada métrica.
+
+| | | | | | | |
+| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
+| | Grupos de Métricas | | | | | |
+| Entidade | [`ENGAGEMENT`](#engagement) | [`BILLING`](#BILLING) | [`VIDEO`](#VIDEO) | [`WEB_CONVERSION`](#WEB_CONVERSION) | [`MOBILE_CONVERSION`](#MOBILE_CONVERSION) | [`LIFE_TIME_VALUE_MOBILE_CONVERSION`](#LIFE_TIME_VALUE_MOBILE_CONVERSION) |
+| `ACCOUNT` | ✔\* | | | | | |
+| `FUNDING_INSTRUMENT` | ✔\* | ✔ | | | | |
+| `CAMPAIGN` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| `LINE_ITEM` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| `PROMOTED_TWEET` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+
+\*Algumas métricas da família `ENGAGEMENT` não estão disponíveis nos níveis de conta e de funding instrument. Veja a seção `ENGAGEMENT` para detalhes.
+
+### Métricas disponíveis por grupo de métricas
+
+#### `ENGAGEMENT`
+
+| | | | | |
+| :-- | :-- | :-- | :-- | :-- |
+| Métrica | Descrição | Segmentação disponível | Tipo de dado | Disponível para Account / Funding Instrument |
+| `engagements` | Número total de engajamentos | ✔ | Array de ints | ✔ |
+| `impressions` | Número total de impressões | ✔ | Array de ints | ✔ |
+| `retweets` | Número total de reposts | ✔ | Array de ints | ✔ |
+| `replies` | Número total de respostas | ✔ | Array de ints | ✔ |
+| `likes` | Número total de curtidas | ✔ | Array de ints | ✔ |
+| `follows` | Número total de follows | ✔ | Array de ints | ✔ |
+| `card_engagements` | Número total de engajamentos em cards | ✔ | Array de ints | |
+| `clicks` | Número total de cliques, incluindo favoritos e outros engajamentos | ✔ | Array de ints | |
+| `app_clicks` | Número de tentativas de instalação de app ou abertura de app | ✔ | Array de ints | |
+| url\_clicks | Total de cliques no link ou Website Card em um anúncio, incluindo earned. | ✔ | Array de ints | |
+| `qualified_impressions` | Número total de impressões qualificadas | ✔ | Array de ints | |
+| `carousel_swipes` | Total de swipes em imagens ou vídeos de Carousel | ✔ | Array de ints | |
+
+#### `BILLING`
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descrição | Segmentação disponível | Tipo de dado |
+| `billed_engagements` | Número total de engajamentos cobrados | ✔ | Array de ints |
+| `billed_charge_local_micro` | Gasto total em micros | ✔ | Array de ints |
+
+#### `VIDEO`
+
+Aviso sobre mudanças na definição de métricas de vídeo:
+
+A métrica `video_total_views` dentro do grupo de métricas `VIDEO` contabilizará qualquer view com pelo menos 50% do vídeo em tela (in-view) por 2 segundos, conforme o padrão MRC.
+
+Nossa definição original de visualização de vídeo, de 100% em tela por pelo menos 3 segundos, continuará disponível como uma nova métrica `video_3s100pct_views` no grupo de métricas `VIDEO`. Para continuar fazendo lance e ser cobrado com base na definição original de view, use o novo bid\_unit `VIEW_3S_100PCT`.
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descrição | Segmentação disponível | Tipo de dado |
+| `video_total_views` | Número total de visualizações de vídeo | ✔ | Array de ints |
+| `video_views_25` | Número total de visualizações em que pelo menos 25% do vídeo foi assistido. | ✔ | Array de ints |
+| `video_views_50` | Número total de visualizações em que pelo menos 50% do vídeo foi assistido. | ✔ | Array de ints |
+| `video_views_75` | Número total de visualizações em que pelo menos 75% do vídeo foi assistido. | ✔ | Array de ints |
+| `video_views_100` | Número total de visualizações em que pelo menos 100% do vídeo foi assistido. | ✔ | Array de ints |
+| `video_cta_clicks` | Total de cliques no call to action | ✔ | Array de ints |
+| `video_content_starts` | Número total de inícios de reprodução do vídeo | ✔ | Array de ints |
+| `video_3s100pct_views` | Número total de visualizações em que pelo menos 3 segundos foram reproduzidos com 100% do vídeo em tela (legado `video_total_views`) | ✔ | Array de ints |
+| `video_6s_views` | Número total de visualizações em que pelo menos 6 segundos do vídeo foram assistidos | ✔ | Array de ints |
+| `video_15s_views` | Número total de visualizações em que pelo menos 15 segundos do vídeo ou 95% da duração total foram assistidos | ✔ | Array de ints |
+
+#### `WEB_CONVERSION`
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descrição | Segmentação disponível | Tipo de dado |
+| `conversion_purchases` | Número de conversões do tipo PURCHASE e o valor de venda e quantidade de pedidos correspondentes | Apenas `PLATFORMS` | Objeto JSON |
+| `conversion_sign_ups` | Número de conversões do tipo SIGN\_UP e o valor de venda e quantidade de pedidos correspondentes | Apenas `PLATFORMS` | Objeto JSON |
+| `conversion_site_visits` | Número de conversões do tipo SITE\_VISIT e o valor de venda e quantidade de pedidos correspondentes | Apenas `PLATFORMS` | Objeto JSON |
+| `conversion_downloads` | Número de conversões do tipo DOWNLOAD e o valor de venda e quantidade de pedidos correspondentes | Apenas `PLATFORMS` | Objeto JSON |
+| `conversion_custom` | Número de conversões do tipo CUSTOM e o valor de venda e quantidade de pedidos correspondentes | Apenas `PLATFORMS` | Objeto JSON |
+
+#### `MOBILE_CONVERSION`
+
+As estatísticas de conversão mobile estão disponíveis apenas para contas de anunciantes habilitadas para MACT.
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descrição | Segmentação disponível | Tipo de dado |
+| `mobile_conversion_spent_credits` | Detalhamento das conversões mobile do tipo SPENT\_CREDIT por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_installs` | Detalhamento das conversões mobile do tipo INSTALL por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_content_views` | Detalhamento das conversões mobile do tipo CONTENT\_VIEW por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_add_to_wishlists` | Detalhamento das conversões mobile do tipo ADD\_TO\_WISHLIST por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_checkouts_initiated` | Detalhamento das conversões mobile do tipo CHECKOUT\_INITIATED por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_reservations` | Detalhamento das conversões mobile do tipo RESERVATION por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_tutorials_completed` | Detalhamento das conversões mobile do tipo TUTORIAL\_COMPLETED por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_achievements_unlocked` | Detalhamento das conversões mobile do tipo ACHIEVEMENT\_UNLOCKED por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_searches` | Detalhamento das conversões mobile do tipo SEARCH por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_add_to_carts` | Detalhamento das conversões mobile do tipo ADD\_TO\_CART por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_payment_info_additions` | Detalhamento das conversões mobile do tipo PAYMENT\_INFO\_ADDITION por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_re_engages` | Detalhamento das conversões mobile do tipo RE\_ENGAGE por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_shares` | Detalhamento das conversões mobile do tipo SHARE por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_rates` | Detalhamento das conversões mobile do tipo RATE por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_logins` | Detalhamento das conversões mobile do tipo LOGIN por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_updates` | Detalhamento das conversões mobile do tipo UPDATE por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_levels_achieved` | Detalhamento das conversões mobile do tipo LEVEL\_ACHIEVED por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_invites` | Detalhamento das conversões mobile do tipo INVITE por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| `mobile_conversion_key_page_views` | Detalhamento das conversões mobile do tipo KEY\_PAGE\_VIEW por post\_view e post\_engagement | ✔ | Objeto JSON |
+| mobile\_conversion\_downloads | Detalhamento das conversões mobile do tipo DOWNLOAD por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| mobile\_conversion\_purchases | Detalhamento das conversões mobile do tipo PURCHASE por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| mobile\_conversion\_sign\_ups | Detalhamento das conversões mobile do tipo SIGN\_UP por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+| mobile\_conversion\_site\_visits | Detalhamento das conversões mobile do tipo SITE\_VISIT por post\_view, post\_engagement, assisted, order\_quantity e sale\_amount | ✔ | Objeto JSON |
+
+#### `LIFE_TIME_VALUE_MOBILE_CONVERSION`
+
+As estatísticas de lifetime de conversão mobile estão disponíveis apenas para contas de anunciantes habilitadas para MACT.
+
+| | | | |
+| :-- | :-- | :-- | :-- |
+| Métrica | Descrição | Segmentação disponível | Tipo de dado |
+| `mobile_conversion_lifetime_value_purchases` | Detalhamento das conversões mobile do tipo PURCHASE | | Objeto JSON |
+| `mobile_conversion_lifetime_value_sign_ups` | Detalhamento das conversões mobile do tipo SIGN\_UP | | Objeto JSON |
+| `mobile_conversion_lifetime_value_updates` | Detalhamento das conversões mobile do tipo UPDATE | | Objeto JSON |
+| `mobile_conversion_lifetime_value_tutorials_completed` | Detalhamento das conversões mobile do tipo TUTORIAL\_COMPLETED | | Objeto JSON |
+| `mobile_conversion_lifetime_value_reservations` | Detalhamento das conversões mobile do tipo RESERVATION | | Objeto JSON |
+| `mobile_conversion_lifetime_value_add_to_carts` | Detalhamento das conversões mobile do tipo ADD\_TO\_CART | | Objeto JSON |
+| `mobile_conversion_lifetime_value_add_to_wishlists` | Detalhamento das conversões mobile do tipo ADD\_TO\_WISHLIST | | Objeto JSON |
+| `mobile_conversion_lifetime_value_checkouts_initiated` | Detalhamento das conversões mobile do tipo CHECKOUT\_INITIATED | | Objeto JSON |
+| `mobile_conversion_lifetime_value_levels_achieved` | Detalhamento das conversões mobile do tipo LEVEL\_ACHIEVED | | Objeto JSON |
+| `mobile_conversion_lifetime_value_achievements_unlocked` | Detalhamento das conversões mobile do tipo ACHIEVEMENT\_UNLOCKED | | Objeto JSON |
+| `mobile_conversion_lifetime_value_shares` | Detalhamento das conversões mobile do tipo SHARE | | Objeto JSON |
+| `mobile_conversion_lifetime_value_invites` | Detalhamento das conversões mobile do tipo INVITE | | Objeto JSON |
+| `mobile_conversion_lifetime_value_payment_info_additions` | Detalhamento das conversões mobile do tipo PAYMENT\_INFO\_ADDITION | | Objeto JSON |
+| `mobile_conversion_lifetime_value_spent_credits` | Detalhamento das conversões mobile do tipo SPENT\_CREDIT | | Objeto JSON |
+| `mobile_conversion_lifetime_value_rates` | Detalhamento das conversões mobile do tipo RATE | | Objeto JSON |
+
+### Segmentação
+
+O relatório de segmentação permite a obtenção de métricas divididas por valores de um determinado tipo de targeting. A segmentação está disponível apenas através das [queries assíncronas de analytics](/x-ads-api/analytics#asynchronous-analytics) devido à sua complexidade significativamente maior.
+
+Desde maio de 2026, apenas os seguintes tipos de segmentação estão habilitados. METROS retorna códigos Nielsen DMA como strings numéricas (819 = Seattle-Tacoma). Tipos de segmentação geográfica como METROS exigem o parâmetro country (96683cc9126741d1 para US).
+
+| | |
+| :-- | :-- |
+| Tipo de segmentação | Parâmetro `country` obrigatório |
+| `AGE` | |
+| `GENDER` | |
+| `METROS` | ✔ |
+| `PLATFORMS` | |
+
+## Métricas derivadas
+
+As métricas de campanha dependem do [objetivo da campanha](/x-ads-api/campaign-management). Use este guia para determinar como calcular métricas derivadas com base nos objetivos em uso.
+
+Qualquer `metric` sem chaves é uma métrica retornada pelos endpoints de [analytics](/x-ads-api/analytics#synchronous-analytics) da Ads API. Qualquer nome cercado por `{chaves}` indica uma métrica derivada para aquela categoria.
+
+### ENGAGEMENTS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `{Total Engagements}` | `promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements` ou `promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows` |
+| `{Engagement Rate}` | `{Total Engagements} / {Impressions}` |
+| `billed_charge_local_micro / {Total Engagements}` | |
+
+### WEBSITE\_CLICKS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `{Link Clicks}` | `promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks` |
+| `{Click Rate}` | `{Link Clicks} / {Impressions}` |
+| `billed_charge_local_micro / {Link Clicks}` | |
+| `conversion_site_visits` | |
+| `{Conversion Rate}` | `conversion_site_visits / {Impressions}` |
+| `billed_charge_local_micro / conversion_site_visits` | |
+
+### APP\_INSTALLS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `{App Clicks}` | `promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks` |
+| `{App Click Rate}` | `{App Clicks} / {Impressions}` |
+| `billed_charge_local_micro / {App Clicks}` | |
+| `billed_charge_local_micro / mobile_conversion_installs` | |
+
+### FOLLOWERS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| `promoted_account_impressions` | |
+| `billed_charge_local_micro / {Impressions} / 1000` | |
+| `promoted_account_follows` | |
+| `{Follow Rate}` | `promoted_account_follow_rate` |
+| `billed_charge_local_micro / promoted_account_follows` | |
+
+### VIDEO\_VIEWS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| | `billed_charge_local_micro / {Impressions} / 1000` |
+| `{Video Views}` | `promoted_video_total_views` |
+| `{Video Rate}` | `promoted_video_total_views / {Impressions}` |
+| `{Cost Per View}` | `billed_charge_local_micro / promoted_video_total_views` |
+
+### QUALIFIED\_IMPRESSIONS
+
+| | |
+| :-- | :-- |
+| Métrica derivada | Cálculo com métricas expostas |
+| `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` | |
+| | `billed_charge_local_micro / {Impressions} / 1000` |
+| `{Qualified Impressions}` | `promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions` |
+| `{Qualified Impression Rate}` | `{Qualified Impressions} / {Impressions}` |
+| `{Cost Per 1000 Qualified Impressions }` | `billed_charge_local_micro / {Qualified Impressions} / 1000` |
+
+### CUSTOM
+
+Para `placement_type` igual a `PROMOTED_ACCOUNT`, consulte o objetivo `FOLLOWERS` acima. Para todos os outros placements com esse objetivo, consulte `ENGAGEMENTS` para as métricas derivadas correspondentes.
+
+## Guias
+
+### Active Entities
+
+#### Introdução
+
+O [endpoint Active Entities](/x-ads-api/analytics#get-stats-accounts-account-id-active-entities) foi pensado para ser usado em conjunto com nossos endpoints [síncrono](/x-ads-api/analytics#get-stats-accounts-account-id) e [assíncrono](/x-ads-api/analytics#asynchronous-analytics) de analytics, pois fornece informações sobre quais campanhas solicitar analytics. Ele faz isso retornando detalhes sobre entidades de anúncios e quando suas métricas mudaram. Usar esse endpoint simplificará bastante seu código e a lógica de busca de analytics.
+
+Este guia traz informações e contexto sobre o endpoint e sua fonte de dados. Também apresenta [diretrizes de uso](#usage) e uma série de [exemplos de requisição](#example), demonstrando como usar Active Entities em conjunto com nossos endpoints de analytics. A [seção Resumo](#summary) traz uma descrição de alto nível da abordagem recomendada.
+
+#### Dados
+
+Sempre que uma métrica de uma entidade de anúncio muda, registramos informações sobre essa alteração. Esses eventos de alteração são armazenados em buckets horários e incluem detalhes sobre a entidade, bem como o horário ao qual a alteração se aplica. Este último é necessário porque os eventos de alteração nem sempre correspondem ao momento em que foram registrados. Ajustes de cobrança são uma razão comum para isso, mas há outras também.
+
+#### Endpoint
+
+### Requisição
+
+As requisições do Active Entities têm escopo nas contas de anúncios e possuem três parâmetros de query obrigatórios: `entity`, `start_time` e `end_time`.
+
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2026-03-05T00:00:00Z&end_time=2026-03-06T00:00:00Z"`
+
+Os seguintes valores de `entity` são suportados: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT` e `PROMOTED_TWEET`. Isso reflete os tipos de entidade que nossos endpoints de analytics suportam.
+
+Os valores de `start_time` e `end_time` devem estar em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) e especificam quais buckets horários consultar. Eles devem ser expressos em horas inteiras.
+
+Esse endpoint também aceita três parâmetros opcionais que podem ser usados para filtrar os resultados: `funding_instrument_ids`, `campaign_ids` e `line_item_ids`. Eles funcionam em todos os níveis da hierarquia de anúncios e com qualquer tipo de `entity` especificado.
+
+### Resposta
+
+A resposta do Active Entities para a requisição acima é mostrada a seguir.
+
+```json
+ {
+ "request": {
+ "params": {
+ "account_id": "18ce54d4x5t",
+ "entity": "PROMOTED_TWEET",
+ "start_time": "2026-03-05T00:00:00Z",
+ "end_time": "2026-03-06T00:00:00Z"
+ }
+ },
+ "data": [
+ {
+ "entity_id": "2r0wxw",
+ "activity_start_time": "2026-03-04T20:55:20Z",
+ "activity_end_time": "2026-03-05T03:43:56Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ },
+ {
+ "entity_id": "2r30fn",
+ "activity_start_time": "2026-03-05T08:11:08Z",
+ "activity_end_time": "2026-03-05T14:40:59Z",
+ "placements": [
+ "ALL_ON_TWITTER",
+ "PUBLISHER_NETWORK"
+ ]
+ }
+ ]
+ }
+```
+
+O array `data` inclui um objeto para cada entidade que deve ser incluída em uma requisição subsequente de analytics. Você não deve solicitar analytics para IDs fora desse conjunto.
+
+Cada objeto inclui quatro campos: `entity_id`, `activity_start_time`, `activity_end_time` e `placements`. Os horários de início e fim de atividade representam o intervalo de tempo ao qual os eventos de alteração da entidade associada se aplicam e, portanto, determinam as datas que devem ser especificadas em requisições subsequentes de analytics. O array `placements` pode conter os seguintes valores: `ALL_ON_TWITTER`, `SPOTLIGHT` e `TREND`. Ele indica quais placements devem ser solicitados para o ID de entidade fornecido.
+
+#### Uso
+
+O endpoint Active Entities deve guiar como as requisições de analytics são feitas. As diretrizes de uso a seguir foram escritas para apoiar a sincronização de analytics, permitindo que parceiros mantenham seus stores de dados sincronizados com a X. Em outras palavras, descreve como executar sincronizações regulares agendadas em segundo plano.
+
+Há duas decisões que um desenvolvedor precisa tomar.
+
+1. Com que frequência solicitar as informações de active entities e, portanto, com que frequência buscar analytics.
+2. Como usar os horários de início e fim de atividade para determinar os valores de `start_time` e `end_time` da requisição de analytics.
+
+Esses pontos são discutidos com mais detalhes em cada uma das duas subseções a seguir, após o resumo.
+
+### Resumo
+
+Use o endpoint Active Entities da seguinte forma para guiar como as requisições de analytics são feitas. Siga este fluxo após decidir com que frequência solicitar informações de active entities e, portanto, com que frequência buscar analytics.
+
+1. Faça a requisição ao Active Entities.
+2. Divida a resposta por placement. Um grupo para `ALL_ON_TWITTER`, um para `SPOTLIGHT` e um para `TREND`.
+3. Para cada grupo de placement, faça o seguinte.
+ 1. Extraia os IDs de entidade.
+ 2. Determine os valores de `start_time` e `end_time` para analytics.
+ - Encontre o menor `activity_start_time`. Arredonde esse valor para baixo.
+ - Encontre o maior `activity_end_time`. Arredonde esse valor para cima.
+ 3. Faça a(s) requisição(ões) de analytics.
+ - Agrupe os IDs de entidade em lotes de 20.
+ - Use os valores de `start_time` e `end_time` do passo 3b.
+ - Especifique o valor de `placement` apropriado.
+ 4. Grave no seu store de dados.
+
+Veja [active\_entities.py](https://github.com/xdevplatform/twitter-python-ads-sdk/blob/master/examples/active_entities.py) como exemplo que usa o SDK em Python.
+
+### Frequência
+
+A resposta à primeira pergunta determina o intervalo de tempo que deve ser usado nas requisições do Active Entities. Por exemplo, ao solicitar as informações de active entities a cada hora, o intervalo de tempo deve ser de uma hora. Ao solicitar essas informações uma vez por dia, o intervalo deve ser de um dia. Em outras palavras, os intervalos de tempo devem ser escolhidos de forma que o `start_time` da requisição atual seja igual ao `end_time` da requisição anterior.
+
+
+ **Observação**: uma mesma janela de tempo deve ser solicitada apenas uma vez. Solicitar uma janela de tempo mais de uma vez levará a requisições de analytics desnecessárias. (Exceção abaixo.)
+
+
+Para parceiros que desejam solicitar analytics várias vezes por hora para a hora _atual_, o mesmo padrão se aplica — a frequência determina o intervalo de tempo. A tabela abaixo mostra exemplos de timestamps de start e end do Active Entities para esse cenário.
+
+| | | |
+| :-- | :-- | :-- |
+| **Horário da requisição** | **Timestamp `start_time`** | **Timestamp `end_time`** |
+| 00:15:00 | 00:00:00 | 00:15:00 |
+| 00:30:00 | 00:15:00 | 00:30:00 |
+| 00:45:00 | 00:30:00 | 00:45:00 |
+| 01:00:00 | 00:45:00 | 01:00:00 |
+
+Dada a forma como os eventos de alteração são armazenados, as quatro requisições do Active Entities acima consultam o mesmo bucket horário, o que é necessário para esse caso de uso. No entanto, após o término da hora atual, esse bucket horário não deve mais ser consultado.
+
+### Horários de atividade
+
+Recomendamos a seguinte abordagem para trabalhar com os horários de início e fim de atividade. Em todos os objetos da resposta do Active Entities, encontre o menor `activity_start_time` e o maior `activity_end_time`. Modifique esses valores arredondando o menor horário de início de atividade para baixo e o maior horário de fim de atividade para cima. Especificamente, defina os timestamps como zero em ambos e adicione um dia ao horário de fim, conforme ilustrado na tabela a seguir. Esses são os horários de início e fim que devem ser especificados nas requisições subsequentes de analytics.
+
+| | |
+| :-- | :-- |
+| **Mín., máx. horários de atividade** | **Horários derivados** |
+| 2026-03-04T20:55:20Z
2026-03-05T14:40:59Z | 2026-03-04T00:00:00Z
2026-03-06T00:00:00Z |
+
+**Observação**: é importante incluir os timestamps com horas, minutos e segundos definidos como zero. Caso contrário, se apenas a data for informada, vamos assumir que você está solicitando analytics começando e terminando à meia-noite no fuso horário da conta de anúncios, o que pode não ser o desejado. Por exemplo, se o menor horário de início de atividade for 2026-02-28T01:30:07Z e o timestamp for omitido para uma conta de anúncios com offset de -08:00:00, a requisição de analytics deixará de capturar alterações que ocorreram entre 01:30 e 08:00.
+
+Como alternativa, se você preferir solicitar analytics apenas para a janela de tempo de atividade retornada, sem expandir para dias inteiros, é possível. Usando essa abordagem, os horários de início e fim derivados seriam 2026-03-04T20:00:00Z e 2026-03-05T15:00:00Z, respectivamente. (Observe que intervalos como esses não são aceitos se você especificar granularidade `DAY` na requisição de analytics.)
+
+#### Exemplo
+
+Esta seção demonstra como usar o Active Entities em conjunto com o endpoint síncrono de analytics. (As respostas foram levemente modificadas para melhor legibilidade.) Neste exemplo, o endpoint Active Entities é chamado no início de cada hora, sempre olhando para a hora anterior. A resposta determina como o endpoint síncrono de analytics é usado.
+
+A primeira requisição ao Active Entities é feita às 03:00:00. A resposta indica que as métricas do line item dvcz7 mudaram e que esses eventos de alteração se aplicam à janela entre 02:02:55 e 02:28:12.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T02:00:00Z&end_time=2026-02-11T03:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": [
+ {
+ "entity_id": "dvcz7",
+ "activity_start_time": "2026-02-11T02:02:55Z",
+ "activity_end_time": "2026-02-11T02:58:12Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ }
+ ]
+ }
+```
+
+Com base nesses horários de início e fim de atividade e usando a abordagem descrita acima, os valores de `start_time` e `end_time` da requisição de analytics são definidos como 2026-02-11T00:00:00Z e 2026-02-12T00:00:00Z, respectivamente. Notamos que o terceiro elemento em cada um dos arrays de métricas abaixo é diferente de zero, como esperado a partir das informações de active entities.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
+```
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 24,
+ "data": [
+ {
+ "id": "dvcz7",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "engagements": [
+ 0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "video_total_views": [
+ 0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ]
+ }
+ }
+ ]
+ }
+ ],
+ "request": {}
+ }
+```
+
+A próxima requisição ao Active Entities acontece às 04:00:00 e olha apenas para a hora anterior. Como mencionado acima, uma janela de tempo deve ser solicitada apenas uma vez. Com base na resposta, vemos que eventos de alteração para esse line item se aplicam _tanto_ a 02:00:00 quanto a 03:00:00. Na requisição subsequente de analytics, esperamos ver alterações em ambas as horas.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T03:00:00Z&end_time=2026-02-11T04:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": [
+ {
+ "entity_id": "dvcz7",
+ "activity_start_time": "2026-02-11T02:07:17Z",
+ "activity_end_time": "2026-02-11T03:49:22Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ }
+ ]
+ }
+```
+
+Além de vermos métricas diferentes de zero para 03:00:00, observamos que impressions, spend e MRC video views foram atualizados em relação aos valores anteriores. As impressions, por exemplo, agora são 2.995 para a hora 02:00:00, acima dos 2.792 anteriores. Isso demonstra como eventos de alteração registrados durante a hora 03:00:00 se aplicam à hora 02:00:00.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
+```
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 24,
+ "data": [
+ {
+ "id": "dvcz7",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "engagements": [
+ 0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "video_total_views": [
+ 0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ]
+ }
+ }
+ ]
+ }
+ ],
+ "request": {}
+ }
+```
+
+A requisição ao Active Entities às 05:00:00, novamente olhando apenas para a hora anterior, mostra que os eventos de alteração se aplicam somente à hora 03:00:00. As mudanças nas métricas de analytics na requisição subsequente refletem isso.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T04:00:00Z&end_time=2026-02-11T05:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": [
+ {
+ "entity_id": "dvcz7",
+ "activity_start_time": "2026-02-11T03:42:39Z",
+ "activity_end_time": "2026-02-11T03:48:48Z",
+ "placements": [
+ "ALL_ON_TWITTER"
+ ]
+ }
+ ]
+ }
+```
+
+A resposta de analytics mostra que somente as métricas para a hora 03:00:00 mudaram; os valores para a hora 02:00:00 são os mesmos da requisição de analytics anterior.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2026-02-11T00:00:00Z&end_time=2026-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`
+```
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 24,
+ "data": [
+ {
+ "id": "dvcz7",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "engagements": [
+ 0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ],
+ "video_total_views": [
+ 0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ ]
+ }
+ }
+ ]
+ }
+ ],
+ "request": {}
+ }
+```
+
+Por fim, às 06:00:00 vemos que não há eventos de alteração adicionais. **Observação**: isso _não_ significa que métricas para esse line item não possam mudar no futuro.
+
+```text
+`twurl -H ads-api.x.com "/12/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2026-02-11T05:00:00Z&end_time=2026-02-11T06:00:00Z"`
+```
+
+```json
+ {
+ "request": {},
+ "data": []
+ }
+```
+
+### Guia Assíncrono
+
+## Referência da API
+
+### Analytics Assíncrono
+
+#### Introdução
+
+Os endpoints assíncronos de analytics permitem que parceiros e anunciantes solicitem métricas por meio do envio de requisições de criação que o servidor processa de modo assíncrono. (Chamamos esses processos de "jobs" assíncronos de analytics.) Com essa abordagem, a conexão do cliente não precisa ficar aberta até que a requisição seja atendida.
+
+Esses endpoints, assim como o equivalente síncrono, permitem que parceiros e anunciantes solicitem estatísticas detalhadas sobre desempenho de campanhas. Eles suportam solicitação de dados para accounts, funding instruments, campaigns, line items, promoted posts e media creatives. A diferença em relação ao endpoint síncrono é que os endpoints assíncronos de analytics suportam intervalos de datas mais longos, de até 90 dias, bem como segmentação. Mais detalhes sobre as diferenças entre os dois podem ser encontrados na nossa página [Visão geral de Analytics](/x-ads-api/analytics).
+
+Ao contrário dos endpoints síncronos, o rate limiting é baseado no número de jobs simultâneos para uma dada conta. Em outras palavras, é baseado no número de jobs que podem estar em estado de processamento ao mesmo tempo. Contamos isso no nível da conta de anúncios.
+
+#### Uso
+
+Obter métricas de campanha usando os endpoints assíncronos de analytics é um processo em várias etapas. Envolve criar um job, verificar se o job terminou de processar e, por fim, baixar os dados. O arquivo de dados deve ser descompactado. As quatro etapas específicas estão descritas abaixo.
+
+1. Crie o job usando o endpoint [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics).
+2. Faça requisições em intervalos regulares ao endpoint [GET stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) para verificar se o job terminou de processar.
+3. Assim que o job terminar de processar, baixe o arquivo de dados.
+4. Descompacte o arquivo de dados.
+
+O objeto de resposta retornado no arquivo de dados segue o mesmo schema JSON da resposta do endpoint síncrono de analytics.
+
+Métricas segmentadas de campanha estão disponíveis apenas através dos endpoints assíncronos de analytics. As métricas de campanha podem ser divididas por localização, gênero, interesse, palavra-chave e muito mais. Para a lista completa de opções, veja a página [Métricas e Segmentação](/x-ads-api/analytics#metrics-and-segmentation). Para solicitar métricas segmentadas, use o parâmetro `segmentation_type` ao criar o job.
+
+#### Exemplo
+
+Esta seção demonstra como usar os endpoints assíncronos de analytics.
+
+Comece criando um job usando o endpoint [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics). O exemplo abaixo solicita métricas de engajamento — como impressões, curtidas, cliques etc. — para um line item específico ao longo de uma semana. (Observe que o intervalo solicitado vai até, mas não inclui, 20 de março, pois o timestamp está definido como meia-noite.)
+
+```text
+$ twurl -X POST -H ads-api.x.com "/12/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2026-03-12T00:00:00Z&end_time=2026-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"
+```
+
+```json
+ {
+ "request": {
+ "params": {
+ "start_time": "2026-03-12T00:00:00Z",
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "placement": "ALL_ON_TWITTER",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ },
+ "data": {
+ "start_time": "2026-03-12T00:00:00Z",
+ "segmentation_type": null,
+ "url": null,
+ "id_str": "1120829647711653888",
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "id": 1120829647711653888,
+ "expires_at": null,
+ "account_id": "18ce54d4x5t",
+ "status": "PROCESSING",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "created_at": "2026-04-01T23:19:46Z",
+ "platform": null,
+ "updated_at": "2026-04-01T23:19:46Z",
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ }
+```
+
+Essa resposta não retorna as métricas do line item. Ela apenas fornece informações sobre o job que você acabou de criar. O ID do job é necessário para verificar o status. Ele é exibido nos atributos `id` e `id_str` da resposta.
+
+Em seguida, você vai querer verificar se o job criado, usando o `id_str` da resposta anterior, terminou de processar, conforme indicado por `"status": "SUCCESS"` na resposta. Isso significa que os dados estão prontos para download. O campo `url` contém o link de download.
+
+```text
+$ twurl -H ads-api.x.com "/12/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"
+```
+
+```json
+ {
+ "request": {
+ "params": {
+ "job_ids": [
+ 1120829647711653888
+ ]
+ }
+ },
+ "next_cursor": "1120828505715920896",
+ "data": [
+ {
+ "start_time": "2026-03-12T00:00:00Z",
+ "segmentation_type": null,
+ "url": "https://ton.twimg.com/advertiser-api-async-analytics/stats_job_1120829647711653888.json.gz",
+ "id_str": "1120829647711653888",
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "id": 1120829647711653888,
+ "expires_at": "2026-04-03T23:19:48Z",
+ "account_id": "18ce54d4x5t",
+ "status": "SUCCESS",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "created_at": "2026-04-01T23:19:46Z",
+ "platform": null,
+ "updated_at": "2026-04-01T23:19:48Z",
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ ]
+ }
+```
+
+Embora estejamos passando um único job ID no exemplo acima, na prática você vai querer usar o parâmetro `job_ids` para verificar o status de múltiplos jobs ao mesmo tempo, especificando até 200 IDs de jobs.
+
+Em seguida, baixe o arquivo de dados usando o valor de `url` listado.
+
+```text
+ $ wget https://ton.twimg.com/advertiser-api-async-analytics/stats_job_1120829647711653888.json.gz
+```
+
+Por fim, descompacte o arquivo de dados.
+
+```text
+`$ gunzip stats_job_1120829647711653888.json.gz`
+```
+
+O conteúdo do arquivo é mostrado abaixo.
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 1,
+ "data": [
+ {
+ "id": "el32n",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 3482
+ ],
+ "tweets_send": null,
+ "qualified_impressions": null,
+ "follows": null,
+ "app_clicks": null,
+ "retweets": [
+ 102
+ ],
+ "unfollows": null,
+ "likes": [
+ 15
+ ],
+ "engagements": [
+ 171
+ ],
+ "clicks": [
+ 30
+ ],
+ "card_engagements": null,
+ "poll_card_vote": null,
+ "replies": null,
+ "carousel_swipes": null
+ }
+ }
+ ]
+ }
+ ],
+ "request": {
+ "params": {
+ "start_time": "2026-03-12T00:00:00Z",
+ "segmentation_type": null,
+ "entity_ids": [
+ "el32n"
+ ],
+ "end_time": "2026-03-20T00:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "platform": null,
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ }
+ }
+```
+
+### Reach e Frequência média
+
+
+
+#### GET stats/accounts/:account\_id/reach/campaigns
+
+Obtenha analytics de reach e frequência média para campanhas específicas.
+
+### Resource URL
+
+`https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns`
+
+### Parâmetros
+
+| Nome | Descrição |
+| :-- | :-- |
+| account\_id _required_ | O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as requisições da Advertiser API, exceto [GET accounts](/x-ads-api/campaign-management/reference#accounts). A conta especificada deve estar associada ao usuário autenticado.
Type: string
Example: `18ce54d4x5t` |
+| campaign\_ids _required_ | Limita a resposta apenas às campanhas desejadas, especificando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 20 IDs.
**Observação**: podem ser fornecidos até 20 IDs de campanha.
Type: string
Example: `8fgzf` |
+| end\_time _required_ | Limita os dados retornados ao horário de término especificado, expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Observação**: deve ser expresso em horas inteiras (0 minutos e 0 segundos).
Type: string
Example: `2026-05-26T07:00:00Z` |
+| start\_time _required_ | Limita os dados retornados ao horário de início especificado, expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Observação**: deve ser expresso em horas inteiras (0 minutos e 0 segundos).
Type: string
Example: `2026-05-19T07:00:00Z` |
+
+### Exemplo de requisição
+
+`GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2026-05-19&end_time=2026-05-26`
+
+### Exemplo de resposta
+
+```json
+ {
+ "request": {
+ "params": {
+ "campaign_ids": [
+ "8fgzf"
+ ],
+ "start_time": "2026-05-19T00:00:00Z",
+ "end_time": "2026-05-26T00:00:00Z",
+ "account_id": "18ce54d4x5t"
+ }
+ },
+ "data_type": "reach",
+ "data": [
+ {
+ "id": "8fgzf",
+ "total_audience_reach": 1217,
+ "average_frequency": 1.01
+ }
+ ]
+ }
+```
+
+#### GET stats/accounts/:account\_id/reach/funding\_instruments
+
+Obtenha analytics de reach e frequência média para funding instruments específicos.
+
+### Resource URL
+
+`https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments`
+
+### Parâmetros
+
+| Nome | Descrição |
+| :-- | :-- |
+| account\_id _required_ | O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as requisições da Advertiser API, exceto [GET accounts](/x-ads-api/campaign-management/reference#accounts). A conta especificada deve estar associada ao usuário autenticado.
Type: string
Example: `18ce54d4x5t` |
+| funding\_instrument\_ids _required_ | Limita a resposta apenas aos funding instruments desejados, especificando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 20 IDs.
**Observação**: podem ser fornecidos até 20 IDs de funding instrument.
Type: string
Example: `lygyi` |
+| end\_time _required_ | Limita os dados retornados ao horário de término especificado, expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Observação**: deve ser expresso em horas inteiras (0 minutos e 0 segundos).
Type: string
Example: `2026-05-26T07:00:00Z` |
+| start\_time _required_ | Limita os dados retornados ao horário de início especificado, expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Observação**: deve ser expresso em horas inteiras (0 minutos e 0 segundos).
Type: string
Example: `2026-05-19T07:00:00Z` |
+
+### Exemplo de requisição
+
+```text
+GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2026-05-19&end_time=2026-05-26
+```
+
+### Exemplo de resposta
+
+```json
+ {
+ "request": {
+ "params": {
+ "funding_instrument_ids": [
+ "lygyi"
+ ],
+ "start_time": "2026-05-19T00:00:00Z",
+ "end_time": "2026-05-26T00:00:00Z",
+ "account_id": "18ce54d4x5t"
+ }
+ },
+ "data_type": "reach",
+ "data": [
+ {
+ "id": "lygyi",
+ "total_audience_reach": 1217,
+ "average_frequency": 1.01
+ }
+ ]
+ }
+```
+
+### Analytics Síncrono
+
+
+
+#### GET stats/accounts/:account\_id
+
+Obtenha analytics síncrono para a conta atual. É permitido um intervalo de tempo máximo (`end_time` - `start_time`) de 7 dias.
+
+### Resource URL
+
+`https://ads-api.x.com/12/stats/accounts/:account_id`
+
+### Parâmetros
+
+| Nome | Descrição |
+| :-- | :-- |
+| account\_id _required_ | O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as requisições da Advertiser API, exceto [GET accounts](/x-ads-api/campaign-management/reference#accounts). A conta especificada deve estar associada ao usuário autenticado.
Type: string
Example: `18ce54d4x5t` |
+| end\_time _required_ | Limita os dados retornados ao horário de término especificado, expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Observação**: deve ser expresso em horas inteiras (0 minutos e 0 segundos).
Type: string
Example: `2026-05-26T07:00:00Z` |
+| entity _required_ | O tipo de entidade para o qual obter dados.
Type: enum
Possible values: `ACCOUNT`, `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET` |
+| entity\_ids _required_ | As entidades específicas para as quais obter dados. Especifique uma lista de IDs de entidade separados por vírgula.
**Observação**: podem ser fornecidos até 20 IDs de entidade.
Type: string
Example: `8u94t` |
+| granularity _required_ | Especifica o quão granulares os dados retornados devem ser.
Type: enum
Possible values: `DAY`, `HOUR`, `TOTAL` |
+| metric\_groups _required_ | As métricas específicas que devem ser retornadas. Especifique uma lista de grupos de métricas separados por vírgula. Para mais informações, consulte [Métricas e Segmentação](/x-ads-api/analytics#metrics-and-segmentation).
**Observação**: dados de `MOBILE_CONVERSION` devem ser solicitados separadamente.
Type: enum
Possible values: `BILLING`, `ENGAGEMENT`, `LIFE_TIME_VALUE_MOBILE_CONVERSION`, `MOBILE_CONVERSION`, `VIDEO`, `WEB_CONVERSION` |
+| placement _required_ | Limita os dados retornados a um placement específico.
**Observação**: apenas um único valor é aceito por requisição. Para entidades que possuem tanto placement X quanto X Audience Platform, são necessárias requisições separadas, uma para cada valor de placement.
Type: enum
Possible values: `ALL_ON_TWITTER`, `SPOTLIGHT`, `TREND` |
+| start\_time _required_ | Limita os dados retornados ao horário de início especificado, expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Observação**: deve ser expresso em horas inteiras (0 minutos e 0 segundos).
Type: string
Example: `2026-05-19T07:00:00Z` |
+
+### Exemplo de requisição
+
+```text
+GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2026-05-19&end_time=2026-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT
+```
+
+### Exemplo de resposta
+
+```json
+ {
+ "data_type": "stats",
+ "time_series_length": 1,
+ "data": [
+ {
+ "id": "8u94t",
+ "id_data": [
+ {
+ "segment": null,
+ "metrics": {
+ "impressions": [
+ 1233
+ ],
+ "tweets_send": null,
+ "qualified_impressions": null,
+ "follows": null,
+ "app_clicks": null,
+ "retweets": null,
+ "likes": [
+ 1
+ ],
+ "engagements": [
+ 58
+ ],
+ "clicks": [
+ 58
+ ],
+ "card_engagements": null,
+ "poll_card_vote": null,
+ "replies": null,
+ "carousel_swipes": null
+ }
+ }
+ ]
+ }
+ ],
+ "request": {
+ "params": {
+ "start_time": "2026-05-19T07:00:00Z",
+ "segmentation_type": null,
+ "entity_ids": [
+ "8u94t"
+ ],
+ "end_time": "2026-05-26T07:00:00Z",
+ "country": null,
+ "placement": "ALL_ON_TWITTER",
+ "granularity": "TOTAL",
+ "entity": "LINE_ITEM",
+ "platform": null,
+ "metric_groups": [
+ "ENGAGEMENT"
+ ]
+ }
+ }
+ }
+```
+
+### Active Entities
+
+
+
+#### GET stats/accounts/:account\_id/active\_entities
+
+Obtenha detalhes sobre quais métricas de analytics de entidades mudaram em um determinado período.
+
+Este endpoint deve ser usado em conjunto com nossos endpoints de analytics. Os resultados deste endpoint indicam para quais entidades de anúncios solicitar analytics. Veja nosso [Guia de Active Entities](/x-ads-api/analytics#active-entities) para orientações de uso.
+
+Os eventos de alteração estão disponíveis em buckets horários.
+
+- Os valores de `start_time` e `end_time` especificam quais buckets horários consultar.
+- O array `data` retornado conterá um objeto para cada entidade que deve ser incluída em requisições subsequentes de analytics.
+- **IMPORTANTE**: as datas que devem ser especificadas em requisições subsequentes de analytics devem ser determinadas com base nos valores `activity_start_time` e `activity_end_time`.
+ - Esses valores representam os intervalos de tempo aos quais os eventos de alteração armazenados _se aplicam_. Isso é retornado por entidade.
+
+**Observação**: é permitido um intervalo de tempo máximo (`end_time` - `start_time`) de 90 dias.
+
+### Resource URL
+
+`https://ads-api.x.com/12/stats/accounts/:account_id/active_entities`
+
+### Parâmetros
+
+| Nome | Descrição |
+| :-- | :-- |
+| account\_id _required_ | O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as requisições da Advertiser API, exceto [GET accounts](/x-ads-api/campaign-management/reference#accounts). A conta especificada deve estar associada ao usuário autenticado.
Type: string
Example: `18ce54d4x5t` |
+| end\_time _required_ | Limita os dados retornados ao horário de término especificado, expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Observação**: deve ser expresso em horas inteiras (0 minutos e 0 segundos).
Type: string
Example: `2026-05-26T07:00:00Z` |
+| entity _required_ | O tipo de entidade para o qual obter dados.
Type: enum
Possible values: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET` |
+| start\_time _required_ | Limita os dados retornados ao horário de início especificado, expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Observação**: deve ser expresso em horas inteiras (0 minutos e 0 segundos).
Type: string
Example: `2026-05-19T07:00:00Z` |
+| campaign\_ids _optional_ | Limita a resposta apenas às entidades associadas às campanhas desejadas, especificando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 200 IDs.
**Observação**: exclusivo com `funding_instrument_ids` e `line_item_ids`.
Type: string
Example: `8wku2` |
+| funding\_instrument\_ids _optional_ | Limita a resposta apenas às entidades associadas aos funding instruments desejados, especificando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 200 IDs.
**Observação**: exclusivo com `campaign_ids` e `line_item_ids`.
Type: string
Example: `lygyi` |
+| line\_item\_ids _optional_ | Limita a resposta apenas às entidades associadas aos line items desejados, especificando uma lista de identificadores separados por vírgula. Podem ser fornecidos até 200 IDs.
**Observação**: exclusivo com `campaign_ids` e `line_item_ids`.