跳转到主要内容

​
引言

Analytics 指标帮助合作伙伴和广告主了解其在 X 上推广内容的表现。这包括展示次数、点击量、视频观看量和花费等信息。此外，合作伙伴和广告主还能按所触达受众的不同细分群体获取详细指标。 Ads API 提供两种获取详细投放效果指标的方式：同步和异步。使用同步 analytics 调用时，请求的指标会随响应直接返回。使用异步 analytics 端点时，请求的指标会在关联“作业”处理完成后，通过可下载的结果文件提供。同步端点支持较短的时间范围，适用于实时优化投放。异步端点支持更长的时间范围，适合拉取更多数据，非常适用于生成报表或进行历史数据回填。

​
详细说明

​
同步 vs. 异步

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

​
使用场景

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

​
请求选项

Analytics 请求以广告账户为作用域，因此需要在资源路径中包含账户 ID。下面列出的请求选项需作为查询参数指定。以下类型的值为必填。
  • 实体：实体类型，以及最多 20 个你希望请求 Analytics 的实体 id
  • 时间范围：开始时间和结束时间，使用 ISO 8601 表示
    • 注意： 必须以整点表示
  • 指标组：一个或多个相关指标集合（参见 Metrics and Segmentation，了解每个指标组包含的指标）
  • 粒度：指定返回指标的聚合级别
  • 投放位置：决定是否为在 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 将返回单日的 Analytics 指标（而非两天），因为该时间范围仅覆盖 24 小时。 细分 细分仅通过我们的异步 Analytics endpoint 提供，允许合作伙伴和广告主按特定定向值拆分并检索指标。要请求细分后的指标，请使用 segmentation_type 请求参数。有关细分选项的更多详情，请参见 Metrics and Segmentation。

​
常见问题

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

​
最佳实践

通过 Ads API 收集分析 data 时的若干最佳实践。

​
速率限制与重试

  • 对于受到速率限制的查询（返回 HTTP 429 状态码），你必须检查 x-rate-limit-reset 标头，并仅在指示的时间点或之后重试。
  • 对于返回 HTTP 503 Service Unavailable 状态码的查询，你必须检查 retry-after 标头，并仅在指示的时间之后重试。
  • 不遵守指定重试时间的应用可能在未提前通知的情况下被撤销或限制对 Ads API 的访问权限。

​
分析指标一览

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

​
获取实时、未分段的 data

  • 始终同时提供 start_time 和 end_time。
  • 不要为超过 7 天的任何实体拉取 data。
  • 理想情况下，请以 HOUR 粒度请求 data，因为你始终可以聚合并汇总指标，以获得 DAY 和 TOTAL 粒度。
  • 理想情况下，请在 line_items 和 promoted_tweets 级别请求 data，因为你始终可以聚合并汇总这些指标，以在整个广告实体层级（即 campaign、funding instrument 或 account 级别）上获得总计。
  • 在你方（本地）保存并存储分析指标的数值。
  • 不要反复查询超过 30 天的 data。此类 data 不会变化，应本地存储。
  • 所有未分段的 data 都是实时的，事件发生后的数秒内即可获得。
  • 将转化指标与非转化指标分开，分别发起请求。

​
获取分段数据

  • 请参阅上文“获取实时、非分段数据”的指南。以下是补充建议。
  • 对于大多数分段数据类型，数据有时在最长 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。如果在创意中使用了媒体或视频应用卡片，MEDIA 和 VIDEO 也适用。
派生指标对外曝光的指标计算方式
CPMbilled_charge_local_micro/impressions/1000
应用点击率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
每次观看成本（CPV）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回复总数✔整数数组✔
likes点赞总数✔整数数组✔
follows关注总数✔整数数组✔
card_engagements卡片互动总数✔整数数组
clicks点击总数，包括点赞等其他互动✔整数数组
app_clicks应用安装或打开的尝试次数✔整数数组
url_clicks广告中链接或网站卡片的总点击次数（含自然获得）✔整数数组
qualified_impressions合格展示总数✔整数数组
carousel_swipes对轮播图片或视频的总滑动次数✔整数数组

​
BILLING

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

​
VIDEO

关于视频指标定义变更的通知： 根据 MRC 标准，VIDEO 指标组中的 video_total_views 指标将统计在画面至少有 50% 处于可视范围且观看时长达到 2 秒的观看次数。 我们最初的观看定义为：画面 100% 可视且至少观看 3 秒。该定义仍将以 VIDEO 指标组中的新指标 video_3s100pct_views 提供。若希望继续基于原始观看定义进行竞价与计费，请使用新提供的 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 和图片等媒体中的总观看次数（自动播放与点击）。✔整数数组
media_engagements在视频、Vine、GIF 和图片等媒体中的总点击次数。✔整数数组

​
WEB_CONVERSION

指标描述可用细分数据类型
conversion_purchasesPURCHASE 类型的转化次数，以及对应的销售金额和订单量仅 PLATFORMSJSON 对象
conversion_sign_upsSIGN_UP 类型的转化次数，以及对应的销售金额和订单量仅 PLATFORMSJSON 对象
conversion_site_visitsSITE_VISIT 类型的转化次数，以及对应的销售金额和订单量仅 PLATFORMSJSON 对象
conversion_downloadsDOWNLOAD 类型的转化次数，以及对应的销售金额和订单量仅 PLATFORMSJSON 对象
conversion_customCUSTOM 类型的转化次数，以及对应的销售金额和订单量仅 PLATFORMSJSON 对象

​
MOBILE_CONVERSION

移动端转化统计仅对已启用 MACT 的广告主帐号提供。
度量说明可用细分数据类型
mobile_conversion_spent_creditsSPENT 类型移动端转化明细_按 Post 维度的信用额度_查看、Post_互动, 协助, 订单_数量与销售_金额✔JSON 对象
mobile_conversion_installs按 Post 维度细分的 INSTALL 类型移动端转化_查看，Post_互动, 辅助, 订单_数量与销售_金额✔JSON 对象
mobile_conversion_content_views按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 维度细分的 CONTENT 类型移动端转化_按 Post 分组查看_查看，Post_互动、辅助、订单_数量和销售_金额✔JSON 对象
mobile_conversion_add_to_wishlists按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 维度细分的 ADD 类型移动端转化_收件人_按 Post 划分的愿望清单_查看，Post_互动、助攻、订单_数量与销售_金额✔JSON 对象
mobile_conversion_checkouts_initiated类型为 CHECKOUT 的移动端转化细分_由 Post 触发_查看，Post_互动、助推、订单_数量与销售_金额✔JSON 对象
mobile_conversion_reservations按 Post 维度细分的 RESERVATION 类型移动端转化_查看，Post_互动, 协助转化, 订单_数量和销售_金额✔JSON 对象
mobile_conversion_tutorials_completed类型为 TUTORIAL 的移动端转化明细_按 Post 统计的完成数_查看，Post_互动、助攻、订单_数量和销售_金额✔JSON 对象
mobile_conversion_achievements_unlocked类型为 ACHIEVEMENT 的移动端转化细分_由 Post 解锁_查看，Post_互动、辅助、订单_数量和销售_金额✔JSON 对象
mobile_conversion_searches按 Post 细分的、类型为 SEARCH 的移动转化_查看，Post_互动、辅助、订单_数量与销售_金额✔JSON 对象
mobile_conversion_add_to_carts按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 细分的 ADD 类型移动端转化_至_按 Post 分类的 CART_浏览、Post_互动、助攻、订单_数量与销售_金额✔JSON 对象
mobile_conversion_payment_info_additionsPAYMENT 类型移动端转化的细分：按 post_view、post_engagement、assisted、order_quantity 和 sale_amount_信息_按 Post 追加_查看，Post_互动、协助、订单_数量与销售_金额✔JSON 对象
mobile_conversion_re_engages类型为 RE 的移动端转化细分（按 post_view、post_engagement、assisted、order_quantity、sale_amount）_按 Post 参与互动_查看, Post_互动、协助、订单_数量与销售_金额✔JSON 对象
mobile_conversion_shares按 Post 细分的 SHARE 类型移动端转化_查看，Post_互动、协助、订单_数量和销售_金额✔JSON 对象
mobile_conversion_rates按 Post 分项统计 RATE 类型的移动端转化_查看，Post_互动、协助、订单_数量和销售_金额✔JSON 对象
mobile_conversion_logins按 Post 细分的 LOGIN 类型移动端转化明细_查看，Post_互动、助攻、订单_数量和销售_金额✔JSON 对象
mobile_conversion_updates按 Post 细分的移动端 UPDATE 类型转化_查看、Post_互动、协助、订单_数量与销售_金额✔JSON 对象
已达成的移动转化级别按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 维度细分的 LEVEL 类型移动端转化_按 Post 统计的达成_查看，Post_互动、协助、订单_数量与销售_金额✔JSON 对象
mobile_conversion_invites按 Post 维度细分 INVITE 类型的移动端转化_查看，Post_互动、助攻、订单_数量和销售_金额✔JSON 对象
mobile_conversion_key_page_views按 KEY 类型划分的移动端转化明细_页面_按 Post 查看_查看和发布_互动度✔JSON 对象
移动端_转化_下载按 Post 细分下载（DOWNLOAD）类型的移动端转化_查看，帖子_互动、协助、订单_数量和销售_金额✔JSON 对象
移动端_转化_购买按 Post 维度细分的移动端 PURCHASE 类型转化_查看，Post_互动、助攻、订单_数量与销售_金额✔JSON 对象
移动端_转化_登录_哎呀按 post_view、post_engagement、assisted、order_quantity 和 sale_amount 维度细分的 SIGN 类型移动端转化_按 Post 升序_查看，Post_互动、辅助、订单_数量、销售_金额✔JSON 对象
移动端_转化_站点_访问次数按 SITE 类型的移动端转化细分_按 Post 访问量_查看，Post_互动、助攻、订单_数量和销售_金额✔JSON 对象

​
LIFE_TIME_VALUE_MOBILE_CONVERSION

仅对已启用 MACT 的广告主账户提供生命周期移动端转化统计。
Metric描述可用细分数据类型
mobile_conversion_lifetime_value_purchases类型为 PURCHASE 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_sign_ups类型为 SIGN_UP 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_updates类型为 UPDATE 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_tutorials_completed类型为 TUTORIAL_COMPLETED 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_reservations类型为 RESERVATION 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_add_to_carts类型为 ADD_TO_CART 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_add_to_wishlists类型为 ADD_TO_WISHLIST 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_checkouts_initiated类型为 CHECKOUT_INITIATED 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_levels_achieved类型为 LEVEL_ACHIEVED 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_achievements_unlocked类型为 ACHIEVEMENT_UNLOCKED 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_shares类型为 SHARE 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_invites类型为 INVITE 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_payment_info_additions类型为 PAYMENT_INFO_ADDITION 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_spent_credits类型为 SPENT_CREDIT 的移动端转化明细JSON 对象
mobile_conversion_lifetime_value_rates类型为 RATE 的移动端转化明细JSON 对象

​
分段

分段报告允许按指定定向类型的取值拆分并检索指标。由于复杂度显著提高，分段仅可通过异步分析查询使用。 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

​
派生指标

广告系列指标取决于其广告系列目标。请使用本指南根据既定目标确定如何计算可用的派生指标。 任何不带花括号的 metric 都是由 Ads API 的分析端点返回的。任何以 {花括号} 括起的名称表示该类别的派生指标。

​
互动

派生指标暴露指标计算方式
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 端点旨在与我们的同步和异步 analytics 端点配合使用，因为它能告知应为哪些广告系列请求 analytics。其原理是返回广告实体的详细信息以及其指标变更的时间。使用此端点可大幅简化你的代码与 analytics 获取逻辑。 本指南提供有关该端点及其数据源的信息与背景，还包括使用指南和一系列示例请求，演示如何将 Active Entities 与我们的 analytics 端点结合使用。摘要部分概述了推荐的方法。

​
数据

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

​
终端节点

​
请求

Active Entities 请求以广告账户为作用域，并包含三个必填查询参数：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。这对应了我们的分析端点所支持的实体类型。 start_time 和 end_time 的值必须使用 ISO 8601 格式，并用于指定要查询的按小时分桶的时间范围。两者必须为整点时间。 此端点还支持三个可选参数，用于筛选结果：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 数组包含一个对象，用于表示在后续 analytics 请求中应包含的每个实体。你不应为不在此集合中的 ID 请求 analytics。 每个对象包含四个字段：entity_id、activity_start_time、activity_end_time 和 placements。活动的开始和结束时间表示关联实体的变更事件适用的时间范围，因此决定了后续 analytics 请求中应指定的日期。placements 数组可包含以下值：ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT 和 TREND。它指示针对给定实体 ID 应请求哪些投放位置。

​
使用说明

Active Entities 端点应当指导如何发起 analytics 请求。以下使用指南旨在支持 analytics 同步，帮助合作伙伴使其数据存储与 Twitter 保持一致。换言之，它说明了如何执行定期安排的后台同步。 开发者需要做出两个决定。
  1. 多久请求一次活动实体信息，从而确定拉取 analytics 的频率。
  2. 如何使用活动开始与结束时间来确定 analytics 请求的 start_time 和 end_time 值。
在下方的两个小节中，这些内容会在摘要之后分别作更详细的说明。

​
摘要

按以下方式使用 Active Entities 端点来确定如何发起 analytics 请求。在你确定请求活跃实体信息的频率，进而确定拉取 analytics 的频率之后，再遵循此流程。
  1. 发起 Active Entities 请求。
  2. 按 placement 将响应拆分：分别为 ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT 和 TREND 各建一个组。
  3. 对每个 placement 组，执行以下操作。
    1. 提取实体 ID。
    2. 确定 analytics 的 start_time 和 end_time 值。
      • 找到最小的 activity_start_time，向下取整。
      • 找到最大的 activity_end_time，向上取整。
    3. 发起 analytics 请求。
      • 将实体 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，并在结束时间上加一天，如下表所示。这些就是后续 analytics 请求中应指定的起止时间。
最小、最大活动时间推导出的时间
2019-03-04T20:55:20Z

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

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

​
示例

本节展示如何将 Active Entities 与同步分析端点结合使用。（为便于阅读，响应已略作调整。）在此示例中，会在每个整点调用一次 Active Entities 端点，每个请求都会查看上一个小时的数据。响应将决定如何使用同步分析端点。 第一次 Active Entities 请求在 03:00:00 发出。响应显示，投放项 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"
          ]
        }
      ]
    }
基于这些活动的开始和结束时间，并按照上文所述的方法，analytics 的 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。在随后的 analytics 请求中，我们预计会看到这两个小时的变更。 
`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 出现非零指标之外，我们还看到展示次数、花费和 MRC 视频观看次数都已从先前的数值更新。以展示次数为例，02:00:00 这一小时现为 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 我们看到没有额外的变更事件。注意：这并不意味着该行项目的指标将来不会发生变化。 
`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 参考文档

​
异步式分析

​
介绍

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

​
用法

通过异步分析端点检索广告系列指标需要按步骤进行：先创建作业，周期性检查作业是否完成处理，最后下载并解压数据文件。具体分为以下四步：
  1. 使用 POST stats/jobs/accounts/:account_id 端点创建作业。
  2. 以固定间隔向 GET stats/jobs/accounts/:account_id 端点发起请求，以确定作业是否已完成处理。
  3. 作业完成处理后，下载数据文件。
  4. 解压数据文件。
数据文件中返回的响应对象与同步分析端点的响应具有相同的 JSON 架构。 细分的广告系列指标仅可通过异步分析端点获取。广告系列指标可按位置、性别、兴趣、关键词等进行细分。有关完整选项列表，请参见指标与细分页面。要请求细分指标，请在创建作业时使用 segmentation_type 请求参数。

​
示例

本节演示如何使用异步 Analytics 端点。 首先通过 POST stats/jobs/accounts/:account_id 端点创建一个作业。下面的示例请求一周内某个特定 line item 的互动指标——例如 impressions、likes、clicks 等。（请注意，请求的时间范围截止但不包含 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"
        ]
      }
    }
此响应不会返回 line item 指标。它仅提供有关你刚创建的作业的信息。需要作业 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
必需		被使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已验证用户关联。

类型：string

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

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

类型：string

示例：8fgzf
end_time
必需		将检索到的 data 限定为指定的结束时间，使用 ISO 8601 表示。

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

类型：string

示例：2017-05-26T07:00:00Z
start_time
必需		将检索到的 data 限定为指定的开始时间，使用 ISO 8601 表示。

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

类型：string

示例：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

​
参数

名称描述
account_id
必填		被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。

类型：string

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

注意：最多可提供 20 个资金工具 ID。

类型：string

示例：lygyi
end_time
必填		将检索到的数据限定到指定的结束时间，采用 ISO 8601 表达。

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

类型：string

示例：2017-05-26T07:00:00Z
start_time
必填		将检索到的数据限定到指定的开始时间，采用 ISO 8601 表达。

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

类型：string

示例：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
必填		将检索到的 data 限定到指定的结束时间，使用 ISO 8601 表示。

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

类型：string

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

类型：enum

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

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

类型：string

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

类型：enum

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

注意：MOBILE_CONVERSION data 应单独请求。

类型：enum

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

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

类型：enum

可能的取值：ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TREND
start_time
必填		将检索到的 data 限定到指定的开始时间，使用 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

检索在指定时间段内分析指标发生变化的实体详情。 此端点应与我们的 analytics 端点配合使用。该端点的结果用于指示应为哪些广告实体请求 analytics。使用指南请参见我们的Active Entities 指南。 变更事件以每小时为单位的分桶提供。
  • start_time 和 end_time 用于指定要查询的每小时时间桶。
  • 返回的 data 数组会为每个需要纳入后续 analytics 请求的实体提供一个对象。
  • 重要：后续 analytics 请求中应指定的日期应根据 activity_start_time 和 activity_end_time 来确定。
    • 这些值表示存储的变更事件所适用的时间范围。按实体返回。
注意：允许的最大时间范围（end_time - start_time）为 90 天。

​
资源 URL

https://ads-api.x.com/12/stats/accounts/:account_id/active_entities

​
参数

名称说明
account_id
必填		受托账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。

类型：string

示例：18ce54d4x5t
end_time
必填		将检索到的 data 限定为指定的结束时间，采用 ISO 8601 表示。

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

类型：string

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

类型：enum

可能的取值：CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE、PROMOTED_ACCOUNT、PROMOTED_TWEET
start_time
必填		将检索到的 data 限定为指定的开始时间，采用 ISO 8601 表示。

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

类型：string

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

注意：与 funding_instrument_ids 和 line_item_ids 互斥。

类型：string

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

注意：与 campaign_ids 和 line_item_ids 互斥。

类型：string

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

注意：与 campaign_ids 和 line_item_ids 互斥。

类型：string

示例：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"
          ]
        }
      ]
    }