跳转到主要内容

​
介绍

分析度量可帮助合作伙伴和广告主了解其在 X 上投放内容的表现，包括曝光量、点击量、视频观看次数和花费等信息。此外，合作伙伴和广告主还可以获取其触达受众各细分群体的详细度量。 X Ads API 提供两种获取详细广告系列绩效度量的方式：同步与异步。对于同步分析调用，请求的度量会随响应返回。对于异步分析 endpoint，请求的度量会在关联的“job”处理完成后，通过可下载的结果文件提供。同步 endpoint 支持较短的时间范围，适合实时优化广告系列。异步 endpoints 支持更长的时间范围，因此用于获取更多数据，适合用于生成报告或进行历史回填。

​
详情

​
同步与异步

下表总结了同步与异步分析 endpoint 之间的差异，旨在帮助开发者选择使用哪一组 endpoint。
功能同步异步
请求速率限制用户级：每 15 分钟 250 次请求账户级：100 个并发*作业
时间范围7 天90 天（未分段）
45 天（分段）
分段否是
响应返回度量 data作业的处理状态**
推荐用例实时优化
用户界面请求		定期同步
回填历史数据
  • 指任意时刻可处于处理状态的作业数量上限。
** 作业成功完成处理后会返回一个 URL，可从该地址下载压缩（gzip）结果文件。除此之外，这些 endpoint 提供相同的功能。

​
用例

共有三类主要的分析用例。
  1. 实时优化：使用性能度量更新正在投放的广告系列
  2. 同步：按计划定期进行后台同步
  3. 新账户启用：回填历史 data
同步分析 endpoint 可用于实时优化，根据过去 5 至 15 分钟内度量的变化更新广告系列。任一 endpoint 均可用于分析同步。请注意，所需的时间范围以及是否需要分段会决定应使用哪个 endpoint。新账户启用应仅使用异步分析 endpoints 进行。（切勿使用同步分析 endpoint 来检索大量 data。） 如果通过后端流程同步度量，异步分析 endpoints 可为仪表板和其他 UI 元素提供支持。你的实现应避免调用异步分析 endpoints 来直接响应用户界面请求。

​
请求选项

分析请求以广告账户为作用域，因此需要在资源路径中包含账户 ID。如下所列的请求选项以 query 参数形式指定。需要提供以下类型的值。
  • 实体：实体类型，以及最多 20 个你希望获取分析数据的实体 id
  • 时间范围：使用 ISO 8601 表达的开始时间和结束时间
    • 注意：必须以整点小时表示
  • 度量组：一个或多个相关度量集合（每个度量组包含的度量请参见 Metrics and Segmentation）
  • 粒度：指定返回度量的汇总层级
  • 投放位置：决定是否为在 X 内或 X 站外投放的广告提取度量
    • 注意：每个请求只能指定单个投放位置值
使用 start_time 和 end_time 请求参数来指定时间范围。这些值必须按以下方式与所选粒度对齐。
  1. TOTAL：可指定任意时间范围（在该 endpoint 的限制内）
  2. DAY：开始时间和结束时间都必须与账户所在时区的午夜对齐
  3. HOUR：可指定任意时间范围（在该 endpoint 的限制内）
结束时间为不包含端点。例如，start_time=2019-01-01T00:00:00Z 和 end_time=2019-01-02T00:00:00Z 的请求将返回一天的分析度量（而非两天），因为该时间范围仅覆盖 24 小时。 分段 仅通过我们的异步分析 endpoint 提供。分段允许合作伙伴和广告主按特定定向值拆分并检索度量。要请求分段度量，请使用 segmentation_type 请求参数。有关分段选项的更多详情，请参见 Metrics and Segmentation。

​
常见问题

为什么 X Ads API 的数值与 X Ads UI 中显示的不一致？
  • 请确保你为所有投放位置都请求了数据：ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT 和 TREND。
  • 请记住，Ads API 中的结束时间为排他；而在 Ads UI 中为含括。
为什么在不同时间请求时数值会发生变化？
  • 一旦报告度量可用，你就可以获取。它们几乎实时提供。但这些早期结果是估算值，因此预期会发生变化。除花费数据外，度量会在 24 小时后最终确定。
  • 花费度量一般在事件发生后 3 天内最终确定。但我们会在事件发生之日起最长 14 天内处理计费数据（例如用于垃圾信息过滤）。
如何确定在特定时间段要请求哪些实体 id？ 为什么分析响应中的所有数值都是 null？
  • 很可能该广告系列在请求的时间段内未产生投放
  • 使用 Active Entities endpoint 来确定应为哪些实体以及在哪个时间段获取分析数据
为什么 API 显示 null，而 UI 显示为 0？
  • UI 选择将这些数值显示为 0，但两者等价。
如何请求与细粒度投放位置（例如 X 时间线）相关的度量？
  • 我们在分析中支持以下投放位置取值：ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT 和 TREND（即 X Audience Platform）
是否可以检索已删除或已暂停实体的度量？
  • 可以。实体状态不影响分析度量的可用性。
为什么分段后的数值与未分段的数值不匹配？
  • 由于数据的生成方式，分段数据并不期望 100% 汇总至未分段数据。
是否可以按多个维度请求分段数据？
  • 我们不支持多重分段。

​
最佳实践

从 X Ads API 收集分析 data 时的最佳实践。

​
请求速率限制与重试

  • 对于触发请求速率限制的查询（返回 HTTP 429 状态码），必须检查 x-rate-limit-reset 头部字段，并仅在该时间点或之后重试。
  • 对于返回 HTTP 503 Service Unavailable 状态码的查询，必须检查 retry-after 头部字段，并仅在所示时间之后重试。
  • 未遵守上述重试时间的应用，可能会在未事先通知的情况下被撤销或限速其对 X Ads API 的访问。

​
分析度量一览

  • 所有分析度量在 24 小时后将锁定且不再变动，billed_charge_local_micro 除外。
  • billed_charge_local_micro 度量在返回 data 后的最多 3 天内为估算值。
  • 24 小时后，该度量可能因超支抵扣（在给定 end_time 之后投放的广告）以及被判定为无效的可计费事件而下降。该度量在 24 小时后仅会有极小变化。
  • 更多信息请参见 Analytics。

​
获取实时、未分段的数据

  • 始终同时提供 start_time 和 end_time。
  • 不要拉取超过 7 天前的实体数据。
  • 建议以 HOUR 粒度请求数据，因为你始终可以先聚合再汇总度量，得到 DAY 和 TOTAL 粒度。
  • 建议在 line_items 和 promoted_tweets 层级请求数据，因为你始终可以聚合并汇总这些度量，以在整个广告实体层级（例如 campaign、funding instrument 或 account 层级）得到总计。
  • 在你这边（本地）保存并存储分析度量的值。
  • 不要重复查询早于 30 天的数据。此类数据不会变化，应在本地存储。
  • 所有未分段数据均为实时，数据应在事件发生后的数秒内即可获取。
  • 将转化类度量与非转化类度量分别放在独立的请求中。

​
获取分段数据

  • 请参考上文“获取实时、非分段数据”的指南。以下提供补充建议。
  • 对于大多数分段数据类型，数据在某些情况下可能在最长 1 小时内不完整。按 INTERESTS 分段的数据可能会延迟最长 12 小时。
  • 由于该信息的生成方式，分段数据的汇总预期不会与非分段数据完全（100%）一致。

​
获取历史数据

  • 在回填数据（例如添加新的广告主帐户）时，可能需要将请求按较小的 start_time 和 end_time 时间段拆分为多次发送。
  • 将抓取范围限制在以 30 天为单位的时间窗口内。
  • 对这些请求进行限速并分散在时间上执行，避免耗尽这些抓取的请求速率限制。

​
示例

你可以在我们的 ads-platform-tools GitHub 代码库中找到一个演示部分最佳实践（fetch_stats）的示例脚本。

​
按目标划分的度量

某个实体适用的度量取决于其广告系列目标。请参考本指南，确定针对每种目标类型应获取的相关度量组，并了解如何计算其他衍生度量。

​
ENGAGEMENTS

相关指标组：ENGAGEMENT 和 BILLING。如果创意中使用了媒体，MEDIA 也适用。
派生指标可用指标计算方式
互动率engagements/impressions
CPEbilled_charge_local_micro/engagements
媒体观看率media_views/impressions

​
WEBSITE_CLICKS 和 WEBSITE_CONVERSIONS

相关指标组：ENGAGEMENT、BILLING 和 WEB_CONVERSION。如果创意中使用了媒体素材，MEDIA 也适用。
派生指标对应公开指标的计算方式
CPMbilled_charge_local_micro/impressions/1000
点击率clicks/impressions
CPLCbilled_charge_local_micro/clicks
总转化量conversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases
转化率总转化量 / impressions
CPAbilled_charge_local_micro / 总转化量

​
APP_INSTALLS 和 APP_ENGAGEMENTS

相关指标组：ENGAGEMENT、BILLING、MOBILE_CONVERSION 和 LIFE_TIME_VALUE_MOBILE_CONVERSION。如果创意中使用了媒体或视频 App 卡片，MEDIA 和 VIDEO 也适用。
派生指标公开指标计算
CPMbilled_charge_local_micro/impressions/1000
App 点击率app_clicks/impressions
CPACbilled_charge_local_micro/app_clicks
CPIbilled_charge_local_micro/mobile_conversion_installs

​
FOLLOWERS

相关指标组：ENGAGEMENT 和 BILLING。如果在创意中使用了媒体，MEDIA 也适用。
派生指标公开指标计算
CPMbilled_charge_local_micro/impressions/1000
关注率follows/impressions
CPFbilled_charge_local_micro/follows
媒体观看率media_views/impressions

​
LEAD_GENERATION

相关指标组：ENGAGEMENT 和 BILLING。如果创意中使用了媒体，MEDIA 也适用。
衍生指标可用指标计算方式
CPMbilled_charge_local_micro/impressions/1000
潜在客户数card_engagements
潜在客户转化率card_engagements/impressions
获取每条潜在客户成本（CPL）billed_charge_local_micro/card_engagements

​
VIDEO_VIEWS

相关指标组：ENGAGEMENT、BILLING 和 VIDEO。
派生指标暴露指标计算方法
CPMbilled_charge_local_micro/impressions/1000
视频观看率video_total_views/impressions
每次观看成本（CPV）billed_charge_local_micro/video_total_views

​
VIDEO_VIEWS_PREROLL

相关指标组：ENGAGEMENT、BILLING 和 VIDEO。
派生指标公开指标计算
CPMbilled_charge_local_micro/impressions/1000
视频观看率video_total_views/impressions
每次观看费用billed_charge_local_micro/video_total_views

​
度量与细分

本文档概述了我们的 Analytics 针对各实体类型所提供的度量，以及各度量可用的细分方式。
度量组
实体ENGAGEMENTBILLINGVIDEOMEDIAWEB_CONVERSIONMOBILE_CONVERSIONLIFE_TIME_VALUE_MOBILE_CONVERSION
ACCOUNT✔*
FUNDING_INSTRUMENT✔*✔
CAMPAIGN✔✔✔✔✔✔✔
LINE_ITEM✔✔✔✔✔✔✔
PROMOTED_TWEET✔✔✔✔✔✔✔
MEDIA_CREATIVE✔✔✔✔✔✔✔
ORGANIC_TWEET✔✔
*ENGAGEMENT 度量组中的部分度量在账户和资金工具级别不可用。详情请参见 ENGAGEMENT 章节。

​
各度量组的可用度量

​
ENGAGEMENT

指标描述可细分数据类型适用于账户/资金工具
engagements总参与次数✔整数数组✔
impressions总展示次数✔整数数组✔
retweets转发总数✔整数数组✔
replies回复总数✔整数数组✔
likeslike 总数✔整数数组✔
follows关注总数✔整数数组✔
card_engagements卡片参与总数✔整数数组
clicks总点击次数（包括收藏与其他参与）✔整数数组
app_clicksApp 安装或打开尝试次数✔整数数组
url_clicks广告中链接或网站卡片的总点击次数（含 earned）✔整数数组
qualified_impressions合格展示总次数✔整数数组
carousel_swipes轮播图片或视频的总滑动次数✔整数数组

​
BILLING

指标说明可分段数据类型
billed_engagements计费互动总数✔整数数组
billed_charge_local_micro本地货币微单位的总支出✔整数数组

​
VIDEO

关于视频度量定义变更的通知： 根据 MRC 标准，VIDEO 度量组中的 video_total_views 将统计任意在屏占比至少 50% 且持续 2 秒的观看。 我们最初的视频观看定义（在屏占比 100% 且至少 3 秒）将以新的 video_3s100pct_views 度量继续在 VIDEO 度量组中提供。若要继续基于原始观看定义进行竞价与计费，请使用新提供的 VIEW_3S_100PCT bid_unit。
MetricDescriptionSegmentation AvailableData Type
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号召性用语按钮总点击次数✔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

​
MEDIA

指标说明可分段统计数据类型
media_views在视频、Vine、GIF 和图片等媒体上的总观看次数（含自动播放与点击播放）。✔int 数组
media_engagements在视频、Vine、GIF 和图片等媒体上的总点击次数。✔int 数组

​
WEB_CONVERSION

指标描述可用细分数据类型
conversion_purchases类型为 PURCHASE 的转化次数，以及对应的销售金额和订单数量仅 PLATFORMSJSON 对象
conversion_sign_ups类型为 SIGN_UP 的转化次数，以及对应的销售金额和订单数量仅 PLATFORMSJSON 对象
conversion_site_visits类型为 SITE_VISIT 的转化次数，以及对应的销售金额和订单数量仅 PLATFORMSJSON 对象
conversion_downloads类型为 DOWNLOAD 的转化次数，以及对应的销售金额和订单数量仅 PLATFORMSJSON 对象
conversion_custom类型为 CUSTOM 的转化次数，以及对应的销售金额和订单数量仅 PLATFORMSJSON 对象

​
MOBILE_CONVERSION

移动转化统计仅对已启用 MACT 的广告主账户提供。
指标描述可用分段数据类型
mobile_conversion_spent_credits按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 SPENT_CREDIT 类型移动转化✔JSON 对象
mobile_conversion_installs按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 INSTALL 类型移动转化✔JSON 对象
mobile_conversion_content_views按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 CONTENT_VIEW 类型移动转化✔JSON 对象
mobile_conversion_add_to_wishlists按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 ADD_TO_WISHLIST 类型移动转化✔JSON 对象
mobile_conversion_checkouts_initiated按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 CHECKOUT_INITIATED 类型移动转化✔JSON 对象
mobile_conversion_reservations按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 RESERVATION 类型移动转化✔JSON 对象
mobile_conversion_tutorials_completed按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 TUTORIAL_COMPLETED 类型移动转化✔JSON 对象
mobile_conversion_achievements_unlocked按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 ACHIEVEMENT_UNLOCKED 类型移动转化✔JSON 对象
mobile_conversion_searches按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 SEARCH 类型移动转化✔JSON 对象
mobile_conversion_add_to_carts按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 ADD_TO_CART 类型移动转化✔JSON 对象
mobile_conversion_payment_info_additions按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 PAYMENT_INFO_ADDITION 类型移动转化✔JSON 对象
mobile_conversion_re_engages按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 RE_ENGAGE 类型移动转化✔JSON 对象
mobile_conversion_shares按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 SHARE 类型移动转化✔JSON 对象
mobile_conversion_rates按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 RATE 类型移动转化✔JSON 对象
mobile_conversion_logins按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 LOGIN 类型移动转化✔JSON 对象
mobile_conversion_updates按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 UPDATE 类型移动转化✔JSON 对象
mobile_conversion_levels_achieved按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 LEVEL_ACHIEVED 类型移动转化✔JSON 对象
mobile_conversion_invites按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 INVITE 类型移动转化✔JSON 对象
mobile_conversion_key_page_views按 post_view 和 post_engagement 分解的 KEY_PAGE_VIEW 类型移动转化✔JSON 对象
mobile_conversion_downloads按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 DOWNLOAD 类型移动转化✔JSON 对象
mobile_conversion_purchases按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 PURCHASE 类型移动转化✔JSON 对象
mobile_conversion_sign_ups按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 SIGN_UP 类型移动转化✔JSON 对象
mobile_conversion_site_visits按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 分解的 SITE_VISIT 类型移动转化✔JSON 对象

​
LIFE_TIME_VALUE_MOBILE_CONVERSION

仅对启用了 MACT 的广告主账户提供全周期移动转化统计数据。
MetricDescriptionSegmentation AvailableData Type
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

​
细分

细分报告允许按特定定向类型的取值拆分并检索度量。由于额外的复杂性较高，细分仅可通过异步分析查询使用。 MEDIA_CREATIVE 或 ORGANIC_TWEET 实体不支持细分。 某些细分类别需要传入额外参数，详见下文。 当按 CITIES 或 POSTAL_CODES 进行细分时，API 将仅返回被定向的位置。按区域和都市的细分会返回被定向与未被定向的位置。
细分类别需要 country 参数需要 platform 参数
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

​
派生度量

Campaign 的度量取决于其 campaign objective。请使用本指南，根据既定目标确定如何计算相应的派生度量。 任何不带花括号的 metric 都由 X Ads API 的 analytics endpoint 返回。任何用 {花括号} 括起的名称表示该类别的派生度量。

​
互动

派生指标公开指标计算
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}
{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

衍生指标可见指标计算
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 和 APP_ENGAGEMENTS

衍生指标公开指标计算方式
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

​
关注者

衍生指标暴露指标计算
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

派生指标暴露指标计算
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

派生指标指标计算公式
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

​
自定义

对于 PROMOTED_ACCOUNT 的 placement_type，请参阅上方的 FOLLOWERS 目标。对于该目标下的其他所有投放，请参阅 ENGAGEMENTS 获取相应的派生度量。

​
使用指南

​
活动实体

​
介绍

Active Entities endpoint 旨在与我们的同步和异步分析 endpoint 搭配使用，因为它提供了应为哪些广告系列请求分析的数据。它通过返回广告实体的详细信息以及其度量变更的时间来实现这一点。使用此 endpoint 将大大简化你的代码和分析拉取逻辑。 本指南包含有关该 endpoint 及其数据源的信息和 context。它还提供了使用指南和一系列示例请求，演示如何将 Active Entities 与我们的分析 endpoint 结合使用。摘要部分提供了推荐方法的高层概述。

​
数据

每当广告实体的某项指标发生变更时，我们都会记录相关信息。这些变更事件按小时分桶存储，包含实体的详情以及变更生效的时间。强调生效时间是必要的，因为变更事件并不总是与其被记录的时间一致。账单调整是常见原因，但也可能有其他情况。

​
endpoint

​
请求

Active Entities 请求以广告账户为作用域，并且需要三个必填的 query（查询）参数：entity、start_time 和 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" 支持以下 entity 取值：CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE、PROMOTED_ACCOUNT 和 PROMOTED_TWEET。这与我们的分析 endpoint 所支持的实体类型一致。 start_time 和 end_time 的值必须采用 ISO 8601 格式，并用来指定要查询的按小时划分的时间桶。它们必须为整点小时。 此 endpoint 还支持三个可选参数用于筛选结果：funding_instrument_ids、campaign_ids 和 line_item_ids。这些参数适用于广告层级的各个级别，并可与任何指定的 entity 类型配合使用。

​
响应

上述请求的 Active Entities 返回结果如下。 
    {
      "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"
          ]
        }
      ]
    }
data 数组为每个应包含在后续分析请求中的实体提供一个对象。你不应为该集合之外的 ID 请求分析。 每个对象包含四个 fields：entity_id、activity_start_time、activity_end_time 和 placements。活动开始时间和结束时间表示相关实体变更事件适用的时间范围，因此决定了在后续分析请求中应指定的日期。placements 数组可包含以下取值：ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT 和 TREND。它表示对于给定实体的 ID 应请求哪些投放位置。

​
使用说明

Active Entities endpoint 应当用来指导如何发起分析请求。以下使用指南旨在支持分析同步，帮助合作伙伴使其数据存储与 Twitter 保持同步。换句话说，它说明如何执行定期的后台同步。 开发者需要做出两个决定：
  1. 多久请求一次活动实体信息，从而多久拉取一次分析数据。
  2. 如何使用活动开始和结束时间来确定分析请求的 start_time 和 end_time 值。
在下文的两个小节中，将在摘要之后对上述内容进行更详细的说明。

​
摘要

以下述方式使用 Active Entities endpoint 来规范分析请求的发起方式。在你确定活跃实体信息的拉取频率，进而确定分析数据的提取频率之后，按以下步骤操作。
  1. 发起 Active Entities 请求。
  2. 按 placement 拆分响应。分别为 ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT 和 TREND 各建一个分组。
  3. 对每个 placement 分组，执行以下操作。
    1. 提取实体 id。
    2. 确定分析的 start_time 和 end_time 值。
      • 找到最小的 activity_start_time，并向下取整。
      • 找到最大的 activity_end_time，并向上取整。
    3. 发起分析请求。
      • 将实体 id 按每批 20 个进行分组。
      • 使用第 3b 步中的 start_time 和 end_time 值。
      • 指定相应的 placement 值。
    4. 写入你的数据存储。
请参阅 active_entities.py，以获取一个使用 Python SDK 的示例。

​
频率

对第一个问题的回答将决定在 Active Entities 请求中应使用的时间范围。例如，如果每小时请求一次活跃实体信息，则时间范围应为一小时；如果每天请求一次，则时间范围应为一天。换言之，应选择时间范围，使当前请求的 start_time 等于上一次请求的 end_time。
注意：同一时间窗口应只请求一次。对同一时间窗口进行多次请求会导致不必要的分析请求。（例外情况见下。）
对于希望在“当前”小时内每小时多次请求分析数据的合作伙伴，同样的规则适用——请求频率决定时间范围。下表展示了该场景下 Active Entities 的示例开始与结束时间戳。
请求时间start_time 时间戳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
鉴于变更事件的存储方式，上述四个 Active Entities 请求都会查询同一个按小时划分的桶，这对于该用例是必要的。不过，在当前小时结束后，就不应再查询该小时桶。

​
活动时间

我们建议按以下方式处理活动的起止时间。在 Active Entities 响应中的所有对象中，找到最小的 activity_start_time 和最大的 activity_end_time。将最小开始时间向下取整、最大结束时间向上取整来调整这些值。具体而言，将两者的小时、分钟和秒都设为 00，并在结束时间上加一天，如下表所示。这些即为后续分析请求中应指定的开始和结束时间。
活动时间最小值与最大值推导时间
2019-03-04T20:55:20Z

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

2019-03-06T00:00:00Z
注意：务必包含小时、分钟和秒均为零的时间戳。否则，如果仅传入日期，我们将默认你请求的分析在广告账户所在时区的午夜开始并在午夜结束，这可能并不理想。例如，若最小活动开始时间为 2019-02-28T01:30:07Z，而对时区偏移为 -08:00:00 的广告账户省略了时间戳，则该分析请求将错过 01:30 到 08:00 之间发生的更改。 另外，如果你希望仅针对返回的活动时间窗口进行分析而不扩展到整天，也可以。采用这种方式，推导出的开始和结束时间分别为 2019-03-04T20:00:00Z 和 2019-03-05T15:00:00Z。（请注意，如果在分析请求中指定了 DAY 粒度，则不接受此类时间范围。）

​
示例

本节演示如何将 Active Entities 与同步分析 endpoint 结合使用。（为便于阅读，响应已略作调整。）在此示例中，Active Entities endpoint 会在每个整点调用，每个请求都会回溯上一小时。响应结果将决定如何使用同步分析 endpoint。 第一次 Active Entities 请求在 03:00:00 发出。响应显示 line item dvcz7 的度量发生了变化，且这些变更事件适用于 02:02:55 至 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"
          ]
        }
      ]
    }
基于这些活动的开始和结束时间，并按照上述方法，分析用的 start_time 和 end_time 分别设为 2019-02-11T00:00:00Z 和 2019-02-12T00:00:00Z。可以看到，下方每个度量数组中的第三个元素均不为零，这与我们根据活跃实体信息的预期一致。 
`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": {}
    }
下一次 Active Entities 请求发生在 04:00:00，并且只会查看前一小时。正如上文所述，每个时间窗口只应请求一次。根据响应可知，此 line item 的变更事件同时适用于 02:00:00 和 03:00:00。在随后的分析请求中，我们预计会看到这两个小时的变更。 
`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"
          ]
        }
      ]
    }
除了在 03:00:00 出现非零度量外，我们还看到 impressions、spend 和 MRC video views 已从先前的数值更新。例如，02:00:00 这一小时的 impressions 现为 2,995，高于此前的 2,792。这表明在 03:00:00 这一小时记录的变更事件会应用到 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": {}
    }
在 05:00:00 的 Active Entities 请求中，同样只查看前一小时，可以看到变更事件仅适用于 03:00:00 这一小时。后续请求中的分析度量变化也印证了这一点。 
`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"
          ]
        }
      ]
    }
分析响应显示，只有 03:00:00 这一小时的度量发生了变化；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,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 的度量将来不会发生变化。 
`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": []
    }

​
异步处理指南

​
API 参考文档

​
异步分析

​
介绍

异步分析 endpoint 允许合作伙伴和广告主通过提交创建请求来获取度量，服务器将以异步方式处理这些请求。（我们将其称为异步分析“作业”。）采用这种方式，客户端无需在请求完成前保持连接。 这些 endpoint 与其同步对应项一样，允许合作伙伴和广告主获取关于广告系列表现的详细统计。它们支持为账户、资金工具、广告系列、投放项、推广 Tweets 和媒体创意请求数据。与同步 endpoint 的区别在于，异步分析 endpoint 支持更长的日期范围（最长 90 天）以及分段。关于二者差异的更多详情，请参见我们的Analytics Overview页面。 与我们的同步 endpoint 不同，请求速率限制基于某个账户的并发作业数量。换言之，它取决于任一时间点处于处理状态的作业数量。我们在广告账户级别进行统计。

​
用法

通过异步分析 endpoint 检索广告系列度量是一个多步骤流程。该流程包括创建作业、轮询检查作业是否已完成处理，最后下载 data。data 文件必须解压。具体分为以下四步：
  1. 使用 POST stats/jobs/accounts/:account_id endpoint 创建作业。
  2. 以固定间隔向 GET stats/jobs/accounts/:account_id endpoint 发起请求，以确定作业是否已完成处理。
  3. 作业处理完成后，下载 data 文件。
  4. 解压 data 文件。
data 文件中返回的响应对象与同步分析 endpoint 的响应具有相同的 JSON 架构。 分段广告系列度量仅可通过异步分析 endpoint 获取。广告系列度量可按位置、性别、兴趣、关键词等维度进行细分。完整选项列表请参见 Metrics and Segmentation 页面。要请求分段度量，请在创建作业时使用 segmentation_type 请求参数。

​
示例

本节演示如何使用异步分析 endpoint。 先使用 POST stats/jobs/accounts/:account_id endpoint 创建一个作业。下面的示例请求某个特定 line item 在一周内的互动度量——例如展示量、like、点击等。（请注意，请求的时间范围截至但不包含 3 月 20 日，因为时间戳设置为午夜。） 
$ 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"
        ]
      }
    }
此响应不返回行项的度量数据。它仅提供有关你刚创建的作业的信息。需要作业ID来检查作业状态。这在响应属性 id 和 id_str 中都有显示。 接下来，你需要根据上一条响应中的 id_str 检查该作业是否已处理完成，可通过响应中的 "status": "SUCCESS" 来判断。这表示数据已可下载。url 字段包含下载链接。 
$ 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"
          ]
        }
      ]
    }
虽然在上述示例中我们只传入了一个作业 ID，但在实际使用中，建议使用 job_ids 参数，一次最多指定 200 个作业 ID，以同时检查多个作业的状态。 接下来，使用列出的 url 值下载数据文件。 
    $ 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
    正在解析 ton.twimg.com (ton.twimg.com)... 72.21.91.70
    正在连接 ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... 已连接。
    HTTP 请求已发送，正在等待响应... 200 OK
    长度：381 [application/gzip]
    正在保存至：'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' [381/381]
最后，解压文件。 
`$ gunzip zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz`
该文件的内容如下。 
`$ 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"
          ]
        }
      }
    }

​
覆盖人数与平均频次

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

获取指定广告活动的触达与平均频次分析。

​
资源 URL

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

​
参数

名称说明
account_id
必填		被使用的账户标识符。该值出现在资源路径中，一般是所有 Advertiser API 请求（GET accounts 除外）的必需参数。所指定的账户必须与已认证用户关联。

Type: string

Example: 18ce54d4x5t
campaign_ids
必填		通过指定以逗号分隔的标识符列表，将响应限定为所需的广告系列。最多可提供 20 个 ID。

注意：最多可提供 20 个广告系列 ID。

Type: string

Example: 8fgzf
end_time
必填		将检索结果限定到指定的结束时间，采用 ISO 8601 表示。

注意：必须以整点表示（0 分钟、0 秒）。

Type: string

Example: 2017-05-26T07:00:00Z
start_time
必填		将检索结果限定到指定的开始时间，采用 ISO 8601 表示。

注意：必须以整点表示（0 分钟、0 秒）。

Type: string

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

​
示例请求

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

​
示例响应

    {
      "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

获取指定资金工具的触达与平均频次分析。

​
资源 URL

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

​
参数

NameDescription
account_id
必填		已杠杆账户的标识符。该参数出现在资源路径中，通常是除 GET accounts 以外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。

Type: string

Example: 18ce54d4x5t
funding_instrument_ids
必填		通过指定以逗号分隔的标识符列表，将响应限定为所需的资金工具。最多可提供 20 个 ID。

Note: 最多可提供 20 个资金工具 ID。

Type: string

Example: lygyi
end_time
必填		将返回的 data 限定到指定的结束时间，使用 ISO 8601 表示。

Note: 必须以整点表示（0 分钟、0 秒）。

Type: string

Example: 2017-05-26T07:00:00Z
start_time
必填		将返回的 data 限定到指定的开始时间，使用 ISO 8601 表示。

Note: 必须以整点表示（0 分钟、0 秒）。

Type: string

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

​
示例请求

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

​
示例响应

    {
      "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
        }
      ]
    }

​
同步分析

​
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 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。

类型：string

示例：18ce54d4x5t
end_time
必填		将检索的数据限定到指定的结束时间，采用 ISO 8601 格式。

注意：必须为整点（0 分钟且 0 秒）。

类型：string

示例：2017-05-26T07:00:00Z
entity
必填		要检索数据的实体类型。

类型：enum

可能的取值：ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids
必填		要检索的具体实体。指定以逗号分隔的实体 id 列表。

注意：最多可提供 20 个实体 id。

类型：string

示例：8u94t
granularity
必填		指定检索数据的粒度。

类型：enum

可能的取值：DAY, HOUR, TOTAL
metric_groups
必填		需要返回的度量组。指定以逗号分隔的度量组列表。更多信息参见 Metrics and Segmentation。

注意：应单独请求 MOBILE_CONVERSION 数据。

类型：enum

可能的取值：BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement
必填		将检索的数据限定到特定投放位置。

注意：每个请求仅接受单一取值。对于同时具有 X 和 X Audience Platform 投放位置的实体，需要分别发起请求，每个投放位置各一个请求。

类型：enum

可能的取值：ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time
必填		将检索的数据限定到指定的开始时间，采用 ISO 8601 格式。

注意：必须为整点（0 分钟且 0 秒）。

类型：string

示例：2017-05-19T07:00:00Z

​
示例请求

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

​
示例响应

    {
      "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"
          ]
        }
      }
    }

​
活动实体

​
GET stats/accounts/:account_id/active_entities

检索在给定时间段内哪些实体的分析度量发生变化的详细信息。 此 endpoint 应与我们的分析类 endpoints 搭配使用。该 endpoint 的结果用于指示应为哪些广告实体请求分析。有关使用指南，请参阅我们的 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

​
Parameters

NameDescription
account_id
required		被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已通过身份验证的用户关联。

Type: string

Example: 18ce54d4x5t
end_time
required		将检索结果限定到指定的结束时间，使用 ISO 8601 表示。

Note: 必须以整点表示（0 分钟、0 秒）。

Type: string

Example: 2017-05-26T07:00:00Z
entity
required		要检索数据的实体类型。

Type: enum

Possible values: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time
required		将检索结果限定到指定的开始时间，使用 ISO 8601 表示。

Note: 必须以整点表示（0 分钟、0 秒）。

Type: string

Example: 2017-05-19T07:00:00Z
campaign_ids
optional		通过指定以逗号分隔的标识符列表，将响应限定为仅包含与目标广告系列关联的实体。最多可提供 200 个 ID。

Note: 与 funding_instrument_ids 和 line_item_ids 互斥。

Type: string

Example: 8wku2
funding_instrument_ids
optional		通过指定以逗号分隔的标识符列表，将响应限定为仅包含与目标资金工具关联的实体。最多可提供 200 个 ID。

Note: 与 campaign_ids 和 line_item_ids 互斥。

Type: string

Example: lygyi
line_item_ids
optional		通过指定以逗号分隔的标识符列表，将响应限定为仅包含与目标投放项关联的实体。最多可提供 200 个 ID。

Note: 与 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=2019-02-28&end_time=2019-03-01

​
示例响应

    {
      "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