Saltar al contenido principal

​
Introducción

Las metrics de analítica ayudan a socios y anunciantes a comprender el rendimiento del contenido que promocionan en X. Esto incluye información como impresiones, clics, reproducciones de video y gasto. Además, los socios y anunciantes pueden obtener metrics detalladas para diversos segmentos de las audiencias a las que alcanzan. La X Ads API admite dos formas de recuperar metrics detalladas de rendimiento de campaña: de manera sincrónica y asincrónica. Con las llamadas sincrónicas de analítica, las metrics solicitadas se devuelven en la respuesta. Con los endpoints asincrónicos de analítica, las metrics solicitadas están disponibles en un archivo de resultados descargable después de que el “job” asociado haya finalizado su procesamiento. El endpoint sincrónico admite periodos cortos y es ideal para optimizaciones de campañas en tiempo real. Los endpoints asincrónicos admiten periodos mucho más largos y, por lo tanto, están destinados a obtener muchos más data, ideales para generar informes o para reposiciones históricas.

​
Detalles

​
Sincrónico vs. asincrónico

Las diferencias entre los endpoints de analíticas sincrónicos y asincrónicos se resumen en la siguiente tabla. Esta información está destinada a ayudar a los desarrolladores a elegir qué conjunto de endpoints utilizar.
CaracterísticaSincrónicoAsincrónico
Límite de tasaA nivel de usuario: 250 solicitudes/15 minutosA nivel de cuenta: 100 trabajos concurrentes*
Rango de tiempo7 días90 días (no segmentado)
45 días (segmentado)
SegmentaciónNoSí
RespuestaDatos de metricsEstado de procesamiento del trabajo**
Caso de uso recomendadoOptimización en tiempo real
Solicitudes de la interfaz de usuario		Sincronizaciones programadas con regularidad
Relleno de datos históricos
  • Esto se refiere al número máximo de trabajos que pueden estar en estado de procesamiento en un momento dado.
** Una vez que el trabajo ha finalizado correctamente, se devuelve una URL. Desde ella se puede descargar el archivo de resultados comprimido (gzip).Fuera de esto, los endpoints ofrecen la misma funcionalidad.

​
Casos de uso

Existen tres casos de uso principales de analítica.
  1. Optimización en tiempo real: usar metrics de rendimiento para actualizar campañas activas
  2. Sincronización: sincronizaciones periódicas en segundo plano
  3. Incorporación de cuentas nuevas: completar data histórica
El endpoint de analítica síncrona puede usarse para la optimización en tiempo real a fin de actualizar campañas en función de cambios en las metrics dentro de los últimos 5 a 15 minutos. Cualquiera de los endpoints puede usarse para la sincronización de analítica. Tenga en cuenta que el intervalo de tiempo deseado y si se requiere segmentación determinarán qué endpoint usar. La incorporación de cuentas nuevas solo debe realizarse usando los endpoints de analítica asíncrona. (El endpoint de analítica síncrona nunca debe usarse para recuperar grandes volúmenes de data). Los endpoints de analítica asíncrona pueden alimentar paneles y otros elementos de la interfaz de usuario si las metrics se sincronizan mediante un proceso de backend. Su implementación debe evitar llamar a los endpoints de analítica asíncrona para atender solicitudes de la interfaz de usuario.

​
Opciones de solicitud

Las solicitudes de analítica se limitan a cuentas de anuncios y, por lo tanto, requieren el id de la cuenta en la ruta del recurso. Las opciones de solicitud, enumeradas a continuación, se especifican como parámetros de query. Se requieren los siguientes tipos de valores.
  • Entidades: el tipo de entidad, así como hasta 20 id de entidades para las que deseas solicitar analítica
  • Rango temporal: 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 metrics relacionadas (consulta Métricas y segmentación para ver la lista de metrics dentro de cada grupo de métricas)
  • Granularidad: especifica el nivel de agregación en el que se deben devolver las metrics
  • Ubicación: determina si las metrics se obtienen para anuncios que se publicaron dentro o fuera de X
    • Nota: solo se puede especificar un único valor de ubicación por solicitud
Usa los parámetros de solicitud start_time y end_time para especificar un rango temporal. Estos valores deben alinearse con la granularidad especificada de la siguiente manera.
  1. TOTAL: especifica cualquier rango temporal (dentro de los límites del endpoint)
  2. DAY: tanto la hora de inicio como la de fin deben alinearse con la medianoche en la zona horaria de la cuenta
  3. HOUR: especifica cualquier rango temporal (dentro de los límites del endpoint)
La hora de fin es exclusiva. Por ejemplo, una solicitud con start_time=2019-01-01T00:00:00Z y end_time=2019-01-02T00:00:00Z devolverá métricas de analítica equivalentes a un solo día (no dos), ya que este rango cubre únicamente un período de 24 horas. Segmentación Disponible solo a través de nuestros endpoints de analítica asíncronos, la segmentación permite a socios y anunciantes recuperar metrics desglosadas por valores de segmentación específicos. Para solicitar metrics segmentadas, utiliza el parámetro de solicitud segmentation_type. Para más detalles sobre las opciones de segmentación, consulta Métricas y segmentación.

​
Preguntas frecuentes

¿Por qué las cifras de la X Ads API no coinciden con lo que se muestra en la X Ads UI?
  • Asegúrate de haber solicitado data para ambas ubicaciones: ALL_ON_TWITTER y PUBLISHER_NETWORK, SPOTLIGHT y TREND.
  • Recuerda que las horas de finalización en la X Ads API son exclusivas; en la X Ads UI son inclusivas.
¿Por qué cambian las cifras según cuándo solicito data?
  • En cuanto las metrics de informes estén disponibles, puedes recuperarlas. Están disponibles casi en tiempo real. No obstante, estos resultados iniciales son estimaciones y, por lo tanto, es esperable que cambien. Las metrics se finalizan después de 24 horas, con la excepción de la data de gasto.
  • Las metrics de gasto generalmente quedan definitivas dentro de los 3 días del evento. Sin embargo, procesamos data de facturación hasta 14 días a partir de la fecha del evento (por ejemplo, para el filtrado de spam).
¿Cómo puedo determinar qué IDs de entidades solicitar para un período de tiempo específico? ¿Por qué todos los valores en la respuesta de analytics son null?
  • Es probable que la campaña no haya tenido entregas durante el período de tiempo solicitado.
  • Usa el endpoint Active Entities para determinar para qué entidades obtener analytics y para qué período de tiempo.
¿Por qué la API muestra valores null mientras que la UI muestra 0?
  • La UI opta por mostrar estos valores como 0, pero los valores son equivalentes.
¿Cómo puedo solicitar metrics asociadas con una ubicación granular, como el timeline de X?
  • Admitimos los siguientes valores de ubicación en analytics: ALL_ON_TWITTER y PUBLISHER_NETWORK, SPOTLIGHT y TREND (es decir, la X Audience Platform).
¿Es posible recuperar metrics para entidades eliminadas o en pausa?
  • Sí. El estado de la entidad no afecta la disponibilidad de las metrics de analytics.
¿Por qué los valores segmentados no coinciden con los no segmentados?
  • No se espera que la data segmentada sume el 100% de la data no segmentada, debido a cómo se deriva esta información.
¿Es posible solicitar data segmentada por múltiples dimensiones?
  • No admitimos la multisegmentación.

​
Mejores prácticas

Algunas mejores prácticas para recopilar data de analytics con la X Ads API.

​
Limitación de tasa y reintentos

  • En las consultas sujetas a limitación de tasa (las que devuelven un código de estado HTTP 429), debe inspeccionar el encabezado x-rate-limit-reset y reintentar solo en o después del momento indicado.
  • En las consultas que resulten en un código de estado HTTP 503 Service Unavailable, debe inspeccionar el encabezado retry-after y reintentar únicamente después del tiempo indicado.
  • Las aplicaciones que no respeten los tiempos indicados para los reintentos podrían ver su acceso a la X Ads API revocado o restringido sin previo aviso.

​
Resumen de las métricas de Analytics

  • Todas las métricas de Analytics quedan fijadas y no cambiarán después de 24 horas, con la excepción de billed_charge_local_micro.
  • La métrica billed_charge_local_micro es una estimación durante hasta 3 días después de que se devuelve la data.
  • Después de 24 horas, esta métrica puede disminuir debido a créditos por gasto excesivo (anuncios publicados después del end_time indicado) y por eventos facturables que se determinen como inválidos. Esta métrica cambia mínimamente después de 24 horas.
  • Consulte Analytics para obtener más información.

​
Obtención de datos en tiempo real no segmentados

  • Proporcione siempre tanto start_time como end_time.
  • No extraiga datos de entidades con más de 7 días de antigüedad.
  • Solicite datos (idealmente) con granularidad HOUR, ya que siempre puede agregarlos y consolidar metrics para obtener granularidad DAY y TOTAL.
  • Solicite datos (idealmente) a nivel de line_items y promoted_tweets, ya que siempre puede agregarlos y consolidar estas metrics para obtener totales en toda la jerarquía de entidades de anuncios (por ejemplo, a nivel de campaña, instrumento de financiación o cuenta).
  • Guarde y almacene localmente los valores de las metrics de analytics en su lado.
  • No realice consultas repetidas para 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 los data deberían estar disponibles en cuestión de segundos tras producirse un evento.
  • Agrupe las metrics de conversión y las metrics que no son de conversión en solicitudes separadas.

​
Obtención de datos segmentados

  • Consulte las directrices proporcionadas para “Obtención de datos en tiempo real no segmentados” más arriba. A continuación se ofrece orientación adicional.
  • Para la mayoría de los tipos de datos segmentados, en ocasiones es posible que los datos no estén completos durante hasta 1 hora. Los datos segmentados por INTERESTS pueden retrasarse hasta 12 horas.
  • No se espera que los datos segmentados coincidan al 100% con los datos no segmentados, debido a cómo se obtiene esta información.

​
Obtención de datos históricos

  • Al rellenar datos históricos (por ejemplo, al agregar una nueva cuenta de anunciante), es posible que deba realizar varias solicitudes en intervalos más pequeños definidos por start_time y end_time.
  • Limite sus consultas a ventanas de 30 días.
  • Aplique control de tráfico a estas solicitudes y distribúyalas en el tiempo para no agotar sus límites de velocidad para estas consultas.

​
Ejemplo

Puedes encontrar un script de ejemplo que muestra algunas de estas buenas prácticas (fetch_stats) en nuestro repositorio ads-platform-tools en GitHub.

​
Métricas por objetivo

Las métricas aplicables a una entidad dependen del objetivo de la campaña. Use esta guía para determinar qué grupos de métricas recuperar para cada tipo de objetivo y cómo calcular métricas derivadas adicionales.

​
ENGAGEMENTS

Grupos de métricas relevantes: ENGAGEMENT y BILLING. MEDIA también aplica si se utiliza contenido multimedia en los creativos.
Métrica derivadaCálculo de la métrica expuesta
Tasa de interacciónengagements/impressions
CPEbilled_charge_local_micro/engagements
Tasa de visualización de mediosmedia_views/impressions

​
WEBSITE_CLICKS y WEBSITE_CONVERSIONS

Grupos de métricas relevantes: ENGAGEMENT, BILLING y WEB_CONVERSION. MEDIA también aplica si se utiliza contenido multimedia en los creativos.
Métrica derivadaCálculo de la métrica expuesta
CPMbilled_charge_local_micro/impressions/1000
Tasa de clicsclicks/impressions
CPLCbilled_charge_local_micro/clicks
Conversiones totalesconversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases
Tasa de conversiónConversiones totales / impressions
CPAbilled_charge_local_micro / Conversiones totales

​
APP_INSTALLS y APP_ENGAGEMENTS

Grupos de métricas relevantes: ENGAGEMENT, BILLING, MOBILE_CONVERSION y LIFE_TIME_VALUE_MOBILE_CONVERSION. MEDIA y VIDEO también son aplicables si se usa una app card de medios o video en los creativos.
Métrica derivadaCálculo de métrica expuesta
CPMbilled_charge_local_micro/impressions/1000
Tasa de clics de Appapp_clicks/impressions
CPACbilled_charge_local_micro/app_clicks
CPIbilled_charge_local_micro/mobile_conversion_installs

​
FOLLOWERS

Grupos de métricas relevantes: ENGAGEMENT y BILLING. MEDIA también aplica si se utiliza contenido multimedia en los creativos.
Métrica derivadaCálculo de métrica expuesta
CPMbilled_charge_local_micro/impressions/1000
Tasa de seguidoresfollows/impressions
CPFbilled_charge_local_micro/follows
Tasa de visualización de mediosmedia_views/impressions

​
LEAD_GENERATION

Grupos de métricas relevantes: ENGAGEMENT y BILLING. MEDIA también aplica si se utiliza contenido multimedia en los creativos.
Métrica derivadaCálculo de la métrica expuesta
CPMbilled_charge_local_micro/impressions/1000
Leadscard_engagements
Tasa de leadscard_engagements/impressions
Costo por leadbilled_charge_local_micro/card_engagements

​
VIDEO_VIEWS

Grupos de métricas relevantes: ENGAGEMENT, BILLING y VIDEO.
Métrica derivadaCálculo de la métrica expuesta
CPMbilled_charge_local_micro/impressions/1000
Tasa de videovideo_total_views/impressions
Costo por visualizaciónbilled_charge_local_micro/video_total_views

​
VIDEO_VIEWS_PREROLL

Grupos de métricas relevantes: ENGAGEMENT, BILLING y VIDEO.
Métrica derivadaCálculo de la métrica expuesta
CPMbilled_charge_local_micro/impressions/1000
Tasa de videovideo_total_views/impressions
Costo por visualizaciónbilled_charge_local_micro/video_total_views

​
Métricas y segmentación

Este documento ofrece una descripción general de las métricas disponibles en nuestra Analytics para cada tipo de entidad, así como de la segmentación disponible para cada métrica.
Grupos de métricas
EntidadENGAGEMENTBILLINGVIDEOMEDIAWEB_CONVERSIONMOBILE_CONVERSIONLIFE_TIME_VALUE_MOBILE_CONVERSION
ACCOUNT✔*
FUNDING_INSTRUMENT✔*✔
CAMPAIGN✔✔✔✔✔✔✔
LINE_ITEM✔✔✔✔✔✔✔
PROMOTED_TWEET✔✔✔✔✔✔✔
MEDIA_CREATIVE✔✔✔✔✔✔✔
ORGANIC_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.

​
Metrics disponibles por grupo de metrics

​
ENGAGEMENT

MétricaDescripciónSegmentación disponibleTipo de datosDisponible para Cuenta / Instrumento de financiación
engagementsNúmero total de engagements✔Arreglo de enteros✔
impressionsNúmero total de impresiones✔Arreglo de enteros✔
retweetsNúmero total de Retweets✔Arreglo de enteros✔
repliesNúmero total de respuestas✔Arreglo de enteros✔
likesNúmero total de likes✔Arreglo de enteros✔
followsNúmero total de seguidores obtenidos✔Arreglo de enteros✔
card_engagementsNúmero total de engagements con la Card✔Arreglo de enteros
clicksNúmero total de clics, incluidos likes y otros engagements✔Arreglo de enteros
app_clicksNúmero de intentos de instalación o apertura de la App✔Arreglo de enteros
url_clicksClics totales en el enlace o en la Website Card de un anuncio, incluidos los obtenidos orgánicamente.✔Arreglo de enteros
qualified_impressionsNúmero total de impresiones cualificadas✔Arreglo de enteros
carousel_swipesDeslizamientos totales en imágenes o videos de Carrusel✔Arreglo de enteros

​
BILLING

MétricaDescripciónSegmentación disponibleTipo de datos
billed_engagementsNúmero total de interacciones facturadas✔Matriz de enteros
billed_charge_local_microGasto total en micros✔Matriz de enteros

​
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 contabilizará cualquier visualización con al menos un 50% del video en pantalla durante 2 segundos, de acuerdo con el estándar MRC. Nuestra definición original de visualización de video (100% en pantalla durante al menos 3 segundos) seguirá disponible como la nueva métrica video_3s100pct_views en el grupo de métricas VIDEO. Para seguir pujando y facturando según la definición original de visualización, use la nueva bid_unit VIEW_3S_100PCT.
MetricDescriptionSegmentation AvailableData Type
video_total_viewsNúmero total de visualizaciones de video✔Array of ints
video_views_25Número total de visualizaciones en las que se vio al menos el 25% del video✔Array of ints
video_views_50Número total de visualizaciones en las que se vio al menos el 50% del video✔Array of ints
video_views_75Número total de visualizaciones en las que se vio al menos el 75% del video✔Array of ints
video_views_100Número total de visualizaciones en las que se vio el 100% del video✔Array of ints
video_cta_clicksTotal de clics en el llamado a la acción✔Array of ints
video_content_startsNúmero total de inicios de reproducción del video✔Array of ints
video_3s100pct_viewsNúmero total de visualizaciones en las que se reprodujeron al menos 3 segundos con el 100% en pantalla (video_total_views heredada)✔Array of ints
video_6s_viewsNúmero total de visualizaciones en las que se vieron al menos 6 segundos del video✔Array of ints
video_15s_viewsNúmero total de visualizaciones en las que se vieron al menos 15 segundos del video o el 95% de la duración total✔Array of ints

​
MEDIA

MétricaDescripciónSegmentación disponibleTipo de dato
media_viewsNúmero total de visualizaciones (autorreproducciones y clics) de contenido multimedia en videos, Vines, GIFs e imágenes.✔Arreglo de enteros
media_engagementsNúmero total de clics en contenido multimedia en videos, Vines, GIFs e imágenes.✔Arreglo de enteros

​
WEB_CONVERSION

MétricaDescripciónSegmentación disponibleTipo de datos
conversion_purchasesNúmero de conversiones de tipo PURCHASE y el importe de venta y cantidad de pedido correspondientesSolo PLATFORMSObjeto JSON
conversion_sign_upsNúmero de conversiones de tipo SIGN_UP y el importe de venta y cantidad de pedido correspondientesSolo PLATFORMSObjeto JSON
conversion_site_visitsNúmero de conversiones de tipo SITE_VISIT y el importe de venta y cantidad de pedido correspondientesSolo PLATFORMSObjeto JSON
conversion_downloadsNúmero de conversiones de tipo DOWNLOAD y el importe de venta y cantidad de pedido correspondientesSolo PLATFORMSObjeto JSON
conversion_customNúmero de conversiones de tipo CUSTOM y el importe de venta y cantidad de pedido correspondientesSolo PLATFORMSObjeto JSON

​
MOBILE_CONVERSION

Las estadísticas de conversiones en dispositivos móviles están disponibles únicamente para las cuentas de anunciante habilitadas para MACT.
MétricaDescripciónSegmentación disponibleTipo de datos
mobile_conversion_spent_creditsDesglose de conversiones móviles de tipo SPENT_CREDIT por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_installsDesglose de conversiones móviles de tipo INSTALL por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_content_viewsDesglose de conversiones móviles de tipo CONTENT_VIEW por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_add_to_wishlistsDesglose de conversiones móviles de tipo ADD_TO_WISHLIST por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_checkouts_initiatedDesglose de conversiones móviles de tipo CHECKOUT_INITIATED por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_reservationsDesglose de conversiones móviles de tipo RESERVATION por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_tutorials_completedDesglose de conversiones móviles de tipo TUTORIAL_COMPLETED por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_achievements_unlockedDesglose de conversiones móviles de tipo ACHIEVEMENT_UNLOCKED por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_searchesDesglose de conversiones móviles de tipo SEARCH por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_add_to_cartsDesglose de conversiones móviles de tipo ADD_TO_CART por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_payment_info_additionsDesglose de conversiones móviles de tipo PAYMENT_INFO_ADDITION por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_re_engagesDesglose de conversiones móviles de tipo RE_ENGAGE por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_sharesDesglose de conversiones móviles de tipo SHARE por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_ratesDesglose de conversiones móviles de tipo RATE por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_loginsDesglose de conversiones móviles de tipo LOGIN por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_updatesDesglose de conversiones móviles de tipo UPDATE por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_levels_achievedDesglose de conversiones móviles de tipo LEVEL_ACHIEVED por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_invitesDesglose de conversiones móviles de tipo INVITE por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_key_page_viewsDesglose de conversiones móviles de tipo KEY_PAGE_VIEW por post_view y post_engagement✔Objeto JSON
mobile_conversion_downloadsDesglose de conversiones móviles de tipo DOWNLOAD por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_purchasesDesglose de conversiones móviles de tipo PURCHASE por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_sign_upsDesglose de conversiones móviles de tipo SIGN_UP por post_view, post_engagement, assisted, order_quantity y sale_amount✔Objeto JSON
mobile_conversion_site_visitsDesglose de conversiones móviles de 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 conversiones móviles acumuladas (lifetime) están disponibles solo para cuentas de anunciantes con MACT habilitado.
MetricDescriptionSegmentation AvailableData Type
mobile_conversion_lifetime_value_purchasesDesglose de conversiones móviles de tipo PURCHASEJSON object
mobile_conversion_lifetime_value_sign_upsDesglose de conversiones móviles de tipo SIGN_UPJSON object
mobile_conversion_lifetime_value_updatesDesglose de conversiones móviles de tipo UPDATEJSON object
mobile_conversion_lifetime_value_tutorials_completedDesglose de conversiones móviles de tipo TUTORIAL_COMPLETEDJSON object
mobile_conversion_lifetime_value_reservationsDesglose de conversiones móviles de tipo RESERVATIONJSON object
mobile_conversion_lifetime_value_add_to_cartsDesglose de conversiones móviles de tipo ADD_TO_CARTJSON object
mobile_conversion_lifetime_value_add_to_wishlistsDesglose de conversiones móviles de tipo ADD_TO_WISHLISTJSON object
mobile_conversion_lifetime_value_checkouts_initiatedDesglose de conversiones móviles de tipo CHECKOUT_INITIATEDJSON object
mobile_conversion_lifetime_value_levels_achievedDesglose de conversiones móviles de tipo LEVEL_ACHIEVEDJSON object
mobile_conversion_lifetime_value_achievements_unlockedDesglose de conversiones móviles de tipo ACHIEVEMENT_UNLOCKEDJSON object
mobile_conversion_lifetime_value_sharesDesglose de conversiones móviles de tipo SHAREJSON object
mobile_conversion_lifetime_value_invitesDesglose de conversiones móviles de tipo INVITEJSON object
mobile_conversion_lifetime_value_payment_info_additionsDesglose de conversiones móviles de tipo PAYMENT_INFO_ADDITIONJSON object
mobile_conversion_lifetime_value_spent_creditsDesglose de conversiones móviles de tipo SPENT_CREDITJSON object
mobile_conversion_lifetime_value_ratesDesglose de conversiones móviles de tipo RATEJSON object

​
Segmentación

Los informes de segmentación permiten recuperar metrics desglosadas por los valores de un tipo de segmentación determinado. La segmentación solo está disponible mediante consultas analíticas asíncronas debido a su mayor complejidad. La segmentación no es compatible con las entidades MEDIA_CREATIVE u ORGANIC_TWEET. Algunos tipos de segmentación requieren pasar parámetros adicionales. Se documentan a continuación. Al segmentar por CITIES o POSTAL_CODES, la API solo devolverá ubicaciones con segmentación aplicada (objetivos). La segmentación por región y área metropolitana devolverá tanto ubicaciones segmentadas como no segmentadas.
Tipo de segmentaciónparámetro country requeridoparámetro platform requerido
AGE
APP_STORE_CATEGORY
AUDIENCES
CITIES✔
CONVERSATIONS
CONVERSION_TAGS
DEVICES✔
EVENTS
GENDER
INTERESTS
KEYWORDS
LANGUAGES
LOCATIONS
METROS✔
PLATFORMS
PLATFORM_VERSIONS✔
POSTAL_CODES✔
REGIONS✔
SLIDES
SIMILAR_TO_FOLLOWERS_OF_USER
TV_SHOWS

​
Métricas derivadas

Las métricas de campaña dependen de su objetivo de campaña. Use esta guía para determinar cómo calcular métricas derivadas según los objetivos establecidos. Cualquier metric sin llaves es un campo devuelto por los endpoint de analytics de la X Ads API. Cualquier nombre entre {llaves} indica una métrica derivada para esa categoría.

​
INTERACCIONES

Métrica derivadaCálculo de 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}
{Media Views}promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media View Rate}{Media Views} / {Impressions}

​
WEBSITE_CLICKS

Métrica derivadaCálculo de 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 y APP_ENGAGEMENTS

Métrica derivadaCálculo de 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

​
SEGUIDORES

Métrica derivadaCálculo de 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
{Media Views}promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media View Rate}{Media Views} / {Impressions}

​
LEAD_GENERATION

Métrica derivadaCálculo de la métrica expuesta
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_tweet_search_card_engagements + promoted_tweet_timeline_card_engagements + promoted_tweet_profile_card_engagements
{Lead Rate}{Leads} / {Impressions}
{Cost Per Lead}billed_charge_local_micro / {Leads}

​
VIDEO_VIEWS

Métrica derivadaCálculo de 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 derivadaCálculo de 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

​
PERSONALIZADO

Para placement_type de PROMOTED_ACCOUNT, consulta el objetivo FOLLOWERS arriba. Para todas las demás ubicaciones con este objetivo, consulta ENGAGEMENTS para las metrics derivadas correspondientes.

​
Guías

​
Entidades activas

​
Introducción

El endpoint de Active Entities está diseñado para usarse junto con nuestros endpoints de analítica sincrónica y asincrónica, ya que proporciona información sobre qué campañas requieren solicitar analítica. Lo hace devolviendo detalles sobre las entidades publicitarias y cuándo cambiaron sus metrics. Usar este endpoint simplificará considerablemente tu código y la lógica para obtener analítica. Esta guía incluye información y contexto sobre el endpoint y su fuente de data. También proporciona directrices de uso y una serie de ejemplos de solicitudes, que muestran cómo usar Active Entities junto con nuestros endpoints de analítica. La sección de resumen ofrece una descripción general 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 intervalos de una hora e incluyen detalles sobre la entidad, así como la hora a la que aplica el cambio. Esto último es necesario porque los eventos de cambio no siempre coinciden con el momento en que se registraron. Los ajustes de facturación son un motivo común, entre otros.

​
Endpoint

​
Solicitud

Las solicitudes de Active Entities se realizan dentro de cuentas de anuncios y tienen tres parámetros de query obligatorios: entity, start_time y end_time. twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-03-05T00:00:00Z&end_time=2019-03-06T00:00:00Z" Se admiten los siguientes valores de entity: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT y PROMOTED_TWEET. Esto refleja los tipos de entidad que admiten nuestros endpoints de analíticas. Los valores de start_time y end_time deben expresarse en ISO 8601 y especifican qué intervalos por hora consultar. Deben indicarse en horas exactas. Este endpoint también admite tres parámetros opcionales que se pueden usar 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 entity especificado.

​
Respuesta

A continuación se muestra la respuesta de Active Entities para la solicitud precedente. 
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-03-05T00:00:00Z",
          "end_time": "2019-03-06T00:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2r0wxw",
          "activity_start_time": "2019-03-04T20:55:20Z",
          "activity_end_time": "2019-03-05T03:43:56Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        },
        {
          "entity_id": "2r30fn",
          "activity_start_time": "2019-03-05T08:11:08Z",
          "activity_end_time": "2019-03-05T14:40:59Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }
La matriz data incluye un objeto por cada entidad que debe incluirse en una solicitud de analíticas posterior. No debes solicitar analíticas para id fuera de este conjunto. Cada objeto incluye cuatro fields: entity_id, activity_start_time, activity_end_time y placements. Las horas de inicio y fin de la actividad representan el intervalo de tiempo al que se aplican los eventos de cambio de la entidad asociada y, por lo tanto, determinan las fechas que deben especificarse en solicitudes de analíticas posteriores. La matriz placements puede incluir los siguientes valores: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT y TREND. Indica qué ubicaciones deben solicitarse para el id de la entidad dada.

​
Uso

El endpoint de Active Entities debe determinar cómo se hacen las solicitudes de analíticas. Las siguientes pautas de uso están diseñadas para admitir la sincronización de analíticas, permitiendo que los partners mantengan sus almacenes de datos sincronizados con X. En otras palabras, describen cómo realizar sincronizaciones periódicas en segundo plano. Hay dos decisiones que debe tomar un desarrollador.
  1. Con qué frecuencia solicitar información de entidades activas y, por ende, con qué frecuencia extraer las analíticas.
  2. Cómo usar las horas de inicio y fin de la actividad para determinar los valores de start_time y end_time de la solicitud de analíticas.
Estos puntos se abordan con mayor detalle en cada una de las dos subsecciones a continuación, después del resumen.

​
Resumen

Usa el endpoint Active Entities de la siguiente manera para definir cómo se realizan las solicitudes de analíticas. Sigue estos pasos después de decidir con qué frecuencia solicitar información de entidades activas y, por lo tanto, con qué frecuencia extraer analíticas.
  1. Realiza la solicitud de Active Entities.
  2. Divide la respuesta por placement. Un grupo para ALL_ON_TWITTER, uno para PUBLISHER_NETWORK, uno para SPOTLIGHT, y uno para TREND.
  3. Para cada grupo de placement, haz lo siguiente.
    1. Extrae los id de entidad.
    2. Determina los valores de start_time y end_time para las analíticas.
      • 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 las solicitudes de analíticas.
      • Agrupa los id de entidad en lotes de 20.
      • Usa los valores de start_time y end_time del punto 3b.
      • Especifica el valor de placement correspondiente.
    4. Escribe en tu almacén de datos.
Consulta active_entities.py como ejemplo que utiliza el SDK de Python.

​
Frecuencia

La respuesta a la primera pregunta determina el intervalo de tiempo que se debe usar en las solicitudes de Active Entities. Por ejemplo, si se solicita información de entidades activas cada hora, el intervalo debe ser de una hora. Si se solicita información de entidades activas una vez al día, el intervalo debe ser de un día. En otras palabras, los intervalos deben seleccionarse de modo que el start_time de la solicitud actual sea igual al end_time de la solicitud anterior.
Nota: Una ventana temporal solo debe solicitarse una vez. Solicitar una ventana temporal más de una vez generará solicitudes de analítica innecesarias. (Excepción a continuación).
Para los partners que deseen solicitar analítica varias veces por hora durante la hora actual, se aplica el mismo patrón: la frecuencia determina el intervalo. La tabla a continuación muestra ejemplos de marcas de tiempo de inicio y fin de Active Entities para este escenario.
Hora de la solicitudMarca de tiempo de start_timeMarca de tiempo de end_time
00:15:0000:00:0000:15:00
00:30:0000:15:0000:30:00
00:45:0000:30:0000:45:00
01:00:0000:45:0001:00:00
Dada la forma en que se almacenan los eventos de cambio, las cuatro solicitudes de Active Entities anteriores consultan el mismo segmento horario, lo cual es necesario para este caso de uso. Sin embargo, una vez finalizada la hora actual, ya no se debe consultar este segmento horario.

​
Tiempos de actividad

Recomendamos el siguiente enfoque para trabajar con los tiempos de inicio y fin de la actividad. En todos los objetos de la respuesta de Active Entities, identifique el activity_start_time mínimo y el activity_end_time máximo. Modifique 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. En concreto, establezca en cero las horas, los minutos y los segundos de ambas marcas de tiempo y agregue un día al tiempo de fin, como se ilustra en la tabla siguiente. Estos son los tiempos de inicio y fin que deben especificarse en solicitudes de analíticas posteriores.
Tiempos mínimos y máximos de actividadTiempos derivados
2019-03-04T20:55:20Z

2019-03-05T14:40:59Z		2019-03-04T00:00:00Z

2019-03-06T00:00:00Z
Nota: Es importante incluir las marcas de tiempo con horas, minutos y segundos en cero. De lo contrario, si solo se pasa la fecha, asumiremos que está solicitando analíticas que comienzan y terminan a la medianoche en la zona horaria de la cuenta de anuncios, lo que puede no ser lo deseado. Por ejemplo, si el tiempo mínimo de inicio de actividad es 2019-02-28T01:30:07Z y se omite la marca de tiempo para una cuenta de anuncios con un desfase de -08:00:00, la solicitud de analíticas omitirá los cambios que ocurrieron entre las 01:30 y las 08:00. Como alternativa, si prefiere solicitar analíticas solo para la ventana de tiempo de actividad devuelta sin ampliarla a días completos, puede hacerlo. Con este enfoque, los tiempos de inicio y fin derivados serían 2019-03-04T20:00:00Z y 2019-03-05T15:00:00Z, respectivamente. (Tenga en cuenta que no se aceptan rangos como estos si especifica la granularidad DAY en la solicitud de analíticas.)

​
Ejemplo

Esta sección muestra cómo usar Active Entities junto con el endpoint de analytics síncrono. (Las respuestas se han modificado ligeramente para facilitar la lectura). En este ejemplo, se invoca el endpoint de Active Entities al inicio de cada hora y cada solicitud analiza la hora anterior. La respuesta determina cómo se utiliza el endpoint de analytics síncrono. La primera solicitud de Active Entities se realiza a las 03:00:00. La respuesta indica que las metrics del line item dvcz7 cambiaron y que esos eventos de cambio se aplican a la ventana entre 02:02:55 y 02:28:12. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T02:00:00Z&end_time=2019-02-11T03:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:02:55Z",
          "activity_end_time": "2019-02-11T02:58:12Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
A partir de estos tiempos de inicio y fin de actividad y utilizando el enfoque descrito anteriormente, los valores de analytics start_time y end_time se establecen en 2019-02-11T00:00:00Z y 2019-02-12T00:00:00Z, respectivamente. Observamos que el tercer elemento de cada uno de los arrays de metrics a continuación es distinto de cero, como esperábamos según la información sobre entidades activas. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "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 considera la hora anterior. Como se mencionó arriba, una ventana temporal debe solicitarse solo una vez. Según la respuesta, vemos que los eventos de cambio para este elemento de línea aplican a las 02:00:00 y 03:00:00. En la solicitud de analítica posterior, esperamos ver cambios en ambas horas. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity= LINE_ITEM&start_time=2019-02-11T03:00:00Z&end_time=2019-02-11T04:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:07:17Z",
          "activity_end_time": "2019-02-11T03:49:22Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
Además de observar metrics distintas de cero para 03:00:00, vemos que las impresiones, el gasto y las visualizaciones de video MRC se han actualizado con respecto a sus valores anteriores. Las impresiones, por ejemplo, ahora son 2,995 para la hora 02:00:00, frente a 2,792. Esto demuestra cómo los eventos de cambio registrados durante la hora 03:00:00 se aplican a la hora 02:00:00. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "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, nuevamente considerando solo la hora anterior, muestra que los eventos de cambio se aplican únicamente a la hora de las 03:00:00. Los cambios en las metrics de analytics en la solicitud posterior reflejan esto. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T04:00:00Z&end_time=2019-02-11T05:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T03:42:39Z",
          "activity_end_time": "2019-02-11T03:48:48Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
La respuesta de analytics muestra que solo las metrics correspondientes a la hora 03:00:00 han cambiado; los valores de la hora 02:00:00 son los mismos que en la solicitud anterior de analytics. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids= dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "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, sin embargo, que las metrics de este ítem de línea no puedan cambiar en el futuro. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T05:00:00Z&end_time=2019-02-11T06:00:00Z"`

    {
      "request": {},
      "data": []
    }

​
Guía asíncrona

​
Referencia de API

​
Análisis asíncrono

​
Introducción

Los endpoints de analytics asíncronos permiten a socios y anunciantes solicitar metrics enviando solicitudes de creación que el servidor procesa de forma asíncrona. (Nos referimos a estos como “jobs” de analytics asíncronos). Con este enfoque, la conexión del cliente no necesita permanecer abierta hasta que la solicitud se haya completado. Estos endpoints, al igual que su contraparte síncrona, permiten a socios y anunciantes solicitar estadísticas detalladas sobre el rendimiento de las campañas. Admiten solicitar data para cuentas, instrumentos de financiación, campañas, line items, Tweets promocionados y creatividades de medios. La diferencia con el endpoint síncrono es que los endpoints de analytics asíncronos admiten rangos de fechas más amplios, de hasta 90 días, así como segmentación. Puedes encontrar más detalles sobre las diferencias entre ambos en nuestra página de Descripción general de Analytics. A diferencia de nuestros endpoints síncronos, el límite de tasa se basa en el número de jobs concurrentes para una cuenta determinada. En otras palabras, se basa en cuántos jobs pueden estar en estado de procesamiento en un momento dado. Esto se contabiliza a nivel de cuenta de anuncios.

​
Uso

Obtener las métricas de campaña mediante los endpoints de analytics asíncronos es un proceso en varios pasos. Consiste en crear un trabajo, comprobar si ha finalizado el procesamiento y, por último, descargar los datos. El archivo de datos debe descomprimirse. A continuación se describen los cuatro pasos específicos.
  1. Cree el trabajo con el endpoint POST stats/jobs/accounts/:account_id.
  2. Realice solicitudes a intervalos regulares al endpoint GET stats/jobs/accounts/:account_id para determinar si el trabajo ha finalizado el procesamiento.
  3. Una vez que el trabajo haya terminado de procesarse, descargue el archivo de datos.
  4. Descomprima el archivo de datos.
El objeto de respuesta incluido en el archivo de datos tiene el mismo esquema JSON que la respuesta del endpoint de analytics síncrono. Las métricas de campaña segmentadas solo están disponibles mediante los endpoints de analytics asíncronos. Las métricas de campaña se pueden desglosar por ubicación, sexo, intereses, palabras clave y más. Para ver la lista completa de opciones, consulte la página Metrics and Segmentation. Para solicitar métricas segmentadas, utilice el parámetro de solicitud segmentation_type al crear el trabajo.

​
Ejemplo

Esta sección muestra cómo usar los endpoints de analytics asíncronos. Comience creando un job con el endpoint POST stats/jobs/accounts/:account_id. El siguiente ejemplo solicita metrics de engagement —como impresiones, likes, clics, etc.— para un line item específico durante una semana. (Tenga en cuenta que el rango de tiempo solicitado llega hasta, pero no incluye, el 20 de marzo, ya que la marca de tiempo está configurada a medianoche). 
$ twurl -X POST -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2019-03-12T00:00:00Z&end_time=2019-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"

    {
      "request": {
        "params": {
          "start_time": "2019-03-12T00:00:00Z",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      },
      "data": {
        "start_time": "2019-03-12T00:00:00Z",
        "segmentation_type": null,
        "url": null,
        "id_str": "1120829647711653888",
        "entity_ids": [
          "el32n"
        ],
        "end_time": "2019-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": "2019-04-23T23:19:46Z",
        "platform": null,
        "updated_at": "2019-04-23T23:19:46Z",
        "metric_groups": [
          "ENGAGEMENT"
        ]
      }
    }
Esta respuesta no devuelve las metrics del elemento de línea. Simplemente proporciona información sobre el trabajo que acaba de crear. Se necesita el id del trabajo para comprobar el estado del trabajo. Esto se muestra en ambos atributos de respuesta id e id_str. A continuación, debe comprobar si el trabajo que ha creado usando el id_str de la respuesta anterior ha terminado de procesarse, como lo indica "status": "SUCCESS" en la respuesta. Esto significa que los data están listos para descargar. El campo url contiene el enlace de descarga. 
$ twurl -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"

    {
      "request": {
        "params": {
          "job_ids": [
            1120829647711653888
          ]
        }
      },
      "next_cursor": "1120828505715920896",
      "data": [
        {
          "start_time": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "url": "https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz",
          "id_str": "1120829647711653888",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER"
          "id": 1120829647711653900,
          "expires_at": "2019-04-25T23:19:48Z",
          "account_id": "18ce54d4x5t",
          "status": "SUCCESS"
          "granularity": "TOTAL"
          "entity": "LINE_ITEM"
          "created_at": "2019-04-23T23:19:46Z",
          "platform": null,
          "updated_at": "2019-04-23T23:19:48Z",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      ]
    }
Aunque en el ejemplo anterior pasamos un único id de trabajo, en la práctica querrá usar el parámetro job_ids para comprobar el estado de varios trabajos a la vez especificando hasta 200 ids de trabajo. A continuación, descargue el archivo de data usando el valor url indicado. 
    $ wget https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    --2019-04-23 17:52:12--  https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    Resolviendo ton.twimg.com (ton.twimg.com)... 72.21.91.70
    Conectando a ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... conectado.
    Solicitud HTTP enviada, esperando respuesta... 200 OK
    Longitud: 381 [application/gzip]
    Guardando en: 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz'

    zBkuuPeEVx-5OygDVcZpqNtwt51Z5 100%[=================================================>]     381  --.-KB/s    in 0s

    2019-04-23 17:52:12 (5.27 MB/s) - 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz' guardado [381/381]
Por último, descomprime el archivo. 
`$ gunzip zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz`
El contenido del archivo se muestra a continuación. 
`$ cat zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.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": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​
Alcance y frecuencia media

​
GET stats/accounts/:account_id/reach/campaigns

Obtén las métricas de alcance y frecuencia promedio de las campañas especificadas.

​
URL del recurso

https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns

​
Parámetros

NombreDescripción
account_id
obligatorio		El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado.

Type: string

Example: 18ce54d4x5t
campaign_ids
obligatorio		Limita la respuesta únicamente a las campañas deseadas especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 20 IDs.

Nota: Se pueden proporcionar hasta 20 IDs de campaña.

Type: string

Example: 8fgzf
end_time
obligatorio		Restringe los datos recuperados a la hora de finalización especificada, expresada en ISO 8601.

Nota: Debe expresarse en horas completas (0 minutos y 0 segundos).

Type: string

Example: 2017-05-26T07:00:00Z
start_time
obligatorio		Restringe los datos recuperados a la hora de inicio especificada, expresada en ISO 8601.

Nota: Debe expresarse en horas completas (0 minutos y 0 segundos).

Type: string

Example: 2017-05-19T07:00:00Z

​
Ejemplo de solicitud

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2017-05-19&end_time=2017-05-26

​
Ejemplo de respuesta

    {
      "request": {
        "params": {
          "campaign_ids": [
            "8fgzf"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-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 métricas de alcance 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

​
Parameters

NameDescription
account_id
required		El identificador de la cuenta apalancada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado.

Type: string

Example: 18ce54d4x5t
funding_instrument_ids
required		Limita la respuesta a los instrumentos de financiación deseados especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 20 IDs.

Note: Se pueden proporcionar hasta 20 IDs de instrumentos de financiación.

Type: string

Example: lygyi
end_time
required		Limita los datos recuperados al tiempo de finalización especificado, expresado en ISO 8601.

Note: Debe expresarse en horas completas (0 minutos y 0 segundos).

Type: string

Example: 2017-05-26T07:00:00Z
start_time
required		Limita los datos recuperados al tiempo de inicio especificado, expresado en ISO 8601.

Note: Debe expresarse en horas completas (0 minutos y 0 segundos).

Type: string

Example: 2017-05-19T07:00:00Z

​
Ejemplo de solicitud

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2017-05-19&end_time=2017-05-26

​
Ejemplo de respuesta

    {
      "request": {
        "params": {
          "funding_instrument_ids": [
            "lygyi"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "lygyi",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }

​
Analítica sincrónica

​
GET stats/accounts/:account_id

Obtiene análisis sincrónicos para la cuenta actual. Se permite un intervalo 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

NameDescription
account_id
obligatorio		El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado.

Type: string

Example: 18ce54d4x5t
end_time
obligatorio		Restringe los datos recuperados al momento de finalización especificado, expresado en ISO 8601.

Nota: Debe expresarse en horas completas (0 minutos y 0 segundos).

Type: string

Example: 2017-05-26T07:00:00Z
entity
obligatorio		El tipo de entidad para la que se recuperarán datos.

Type: enum

Possible values: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids
obligatorio		Las entidades específicas para las que se recuperarán datos. Especifique una lista de ids de entidad separada por comas.

Nota: Se pueden proporcionar hasta 20 ids de entidad.

Type: string

Example: 8u94t
granularity
obligatorio		Especifique el nivel de granularidad de los datos recuperados.

Type: enum

Possible values: DAY, HOUR, TOTAL
metric_groups
obligatorio		Los metrics específicos que se deben devolver. Especifique una lista de grupos de metrics separada por comas. Para obtener más información, consulte Metrics and Segmentation.

Nota: Los datos de MOBILE_CONVERSION deben solicitarse por separado.

Type: enum

Possible values: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement
obligatorio		Restringe los datos recuperados a una ubicación específica.

Nota: Solo se acepta un valor por solicitud. Para entidades con ubicación tanto en X como en X Audience Platform, se requieren solicitudes separadas, una por cada valor de ubicación.

Type: enum

Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time
obligatorio		Restringe los datos recuperados al momento de inicio especificado, expresado en ISO 8601.

Nota: Debe expresarse en horas completas (0 minutos y 0 segundos).

Type: string

Example: 2017-05-19T07:00:00Z

​
Ejemplo de solicitud

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2017-05-19&end_time=2017-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT

​
Respuesta de ejemplo

    {
      "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": "2017-05-19T07:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "8u94t"
          ],
          "end_time": "2017-05-26T07:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​
Entidades activas

​
GET stats/accounts/:account_id/active_entities

Recupera detalles sobre qué entidades han cambiado sus metrics de analytics en un periodo 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 entidades activas para conocer las pautas de uso. Los eventos de cambio están disponibles en intervalos horarios.
  • Los valores de start_time y end_time especifican qué intervalos horarios consultar.
  • 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 intervalos de tiempo a los que se aplican los eventos de cambio almacenados. Esto se devuelve por entidad.
Nota: Se permite un intervalo 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

NameDescription
account_id
required		El identificador de la cuenta asociada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado.

Type: string

Example: 18ce54d4x5t
end_time
required		Limita los datos recuperados hasta la hora de finalización especificada, expresada en ISO 8601.

Nota: Debe expresarse en horas completas (0 minutos y 0 segundos).

Type: string

Example: 2017-05-26T07:00:00Z
entity
required		El tipo de entidad para la que se recuperarán datos.

Type: enum

Possible values: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time
required		Limita los datos recuperados desde la hora de inicio especificada, expresada en ISO 8601.

Nota: Debe expresarse en horas completas (0 minutos y 0 segundos).

Type: string

Example: 2017-05-19T07:00:00Z
campaign_ids
optional		Limita la respuesta solo a las entidades asociadas con las campañas deseadas especificando una lista de identificadores separada por comas. Se pueden proporcionar hasta 200 IDs.

Nota: Mutuamente excluyente con funding_instrument_ids y line_item_ids.

Type: string

Example: 8wku2
funding_instrument_ids
optional		Limita la respuesta solo a las entidades asociadas con los instrumentos de financiación deseados especificando una lista de identificadores separada por comas. Se pueden proporcionar hasta 200 IDs.

Nota: Mutuamente excluyente con campaign_ids y line_item_ids.

Type: string

Example: lygyi
line_item_ids
optional		Limita la respuesta solo a las entidades asociadas con los line items deseados especificando una lista de identificadores separada por comas. Se pueden proporcionar hasta 200 IDs.

Nota: Mutuamente excluyente con campaign_ids y funding_instrument_ids.

Type: string

Example: 8v7jo

​
Ejemplo de solicitud

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-02-28&end_time=2019-03-01

​
Ejemplo de respuesta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-02-28T08:00:00Z",
          "end_time": "2019-03-01T08:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2mvb28",
          "activity_start_time": "2019-02-28T01:30:07Z",
          "activity_end_time": "2019-03-01T07:42:55Z",
          "placements": [
            "ALL_ON_TWITTER",
          ]
        },
        {
          "entity_id": "2mvb29",
          "activity_start_time": "2019-02-27T11:30:07Z",
          "activity_end_time": "2019-03-01T07:42:50Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK",
          ]
        },
        {
          "entity_id": "2mvfan",
          "activity_start_time": "2019-02-27T09:00:05Z",
          "activity_end_time": "2019-03-01T06:06:36Z",
          "placements": [
            "PUBLISHER_NETWORK",
          ]
        },
        {
          "entity_id": "2n17dx",
          "activity_start_time": "2019-02-28T02:02:26Z",
          "activity_end_time": "2019-03-01T07:52:44Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }
⌘I