广告主 API
您可以推广什么？
- 推广广告是由广告主购买的常规广告，旨在接触更广泛的用户群体，或激发现有粉丝的互动。
- 当广告主为在 X 上的位置付费时，推广广告会明确标示为“推广”。在其他所有方面，推广广告与普通广告完全相同，可以被转发、回复、点赞等操作。它们遵循标准的投放规则，并使用 POST statuses/update 创建。
- “仅限推广”推文， 通过 POST accounts/:account_id/tweet 创建，可用于推广推文活动，但不会向粉丝投放或出现在公共时间线上。要检索某个账户的仅限推广推文列表，请使用 GET accounts/:account_id/scoped_timeline。
- 推广账户是“谁值得关注”功能的一部分，该功能会向用户推荐他们当前未关注但可能感兴趣的账户。推广账户有助于向用户介绍更多种类他们可能喜欢的账户。
- 时间线推广账户，将推广推文与推广账户广告系列关联，并在用户时间线中显示。
广告系列和广告组（广告项）
分析
X Ads API 提供了一组分析端点，用于跟踪和优化广告性能。有关更多信息，请参阅 Analytics 和 Analytics Best Practices。 对于计费指标，数据可能在事件发生后三天内才会最终确定。在此之前，该数据应视为估算值。最终计费数量始终小于估算金额。计费数量已针对垃圾流量和相关低质量流量进行修正。有关时间的其他注意事项，请参阅 Timezones。创建广告系列 - 逐步操作
-t 跟踪调用，这大致相当于 cURL 的 -v 选项。
在本示例中，我们将创建一个关键词定位的推广广告系列。
- 获取账户 id。
- 检索资金工具 ID。
- 创建广告系列并将其与资金工具关联。
- 创建与广告活动关联的广告项。
- 创建与行项目关联的目标定位配置文件。
- 最后，取消投放项的暂停。
基于目标的广告系列
objective。
投放项写入端点中使用的参数，并在读取端点中返回的，是 objective。该字段的当前可能值为：
APP_ENGAGEMENTSAPP_INSTALLSFOLLOWERSENGAGEMENTSREACHVIDEO_VIEWSPREROLL_VIEWSWEBSITE_CLICKS
APP_ENGAGEMENTS 的 CPAC、APP_INSTALLS 的 CPAC 或 CPI、WEBSITE_CLICKS 的 CPLC、FOLLOWERS 的 CPF、ENGAGEMENTS 的 CPE，以及 REACH 的 CPM。
移动应用推广广告系列必须包含 APP_ENGAGEMENTS 或 APP_INSTALLS 目标。
注意： 同一广告系列下不允许使用不同目标的投放项。
| 广告系列目标 | API 目标 | 推文中的媒体 | 定价模型 |
|---|---|---|---|
| 应用重新参与 | APP_ENGAGEMENTS | 需要图像或视频应用下载卡。 | CPAC |
| 应用安装 | APP_INSTALLS | 需要图像或视频应用下载卡。 | CPAC 或 CPI（使用 charge_by 设置） |
| 覆盖 | REACH | 无限制。 | CPM |
| 粉丝 | FOLLOWERS | 推文不是必需的，但推荐使用。粉丝广告系列的推文没有媒体限制，尽管我们推荐仅使用纯文本推文。更多信息 | CPF |
| 互动 | ENGAGEMENTS | 无限制。 | CPE |
| 视频观看 | VIDEO_VIEWS | 需要视频对话卡、视频或 GIF。 | CPV 或每 3 秒/100% 观看成本 |
| 前贴片观看 | PREROLL_VIEWS | 需要视频。 | CPV 或每 3 秒/100% 观看成本 |
| 网站点击 | WEBSITE_CLICKS | 推荐使用网站卡，但不是必需的。推文必须包含网站卡或网站链接（不能两者同时使用）。 | CPLC |
资金工具
funding_instruments 的列表，请参阅 GET accounts/:account_id/funding_instruments 和 GET accounts/:account_id/funding_instruments/:funding_instrument_id，以查看特定资金工具的详细信息。
资金工具属性
account_id、资金工具 id、资金工具 type、description 和 io_header（插入订单标头 ID）。请注意，一个 io_header 可以与多个资金工具关联。
资金能力：able_to_fund 和 reasons_not_able_to_fund。
时间：created_at、updated_at、start_time 和 end_time，以字符串表示，格式为“%Y-%m-%dT%l:%M:%S%z”。
布尔状态：paused、deleted 和 cancelled（true 或 false）。
财务：currency (ISO-4217 格式)、credit_limit_local_micro、credit_remaining_local_micro 和 funded_amount_local_micro。货币的值以微单位表示。对于 USD，$5.50 被编码为 5.50*1e6，即 5,500,000。要表示“完整值”，您需要将本地微单位值乘以 1e6 (1_000_000)，适用于所有货币。
属性详情
credit_limit_local_micro 仅适用于 CREDIT_CARD 或 CREDIT_LINE 类型的资金工具，并表示该工具的信用限额。
funded_amount_local_micro 仅适用于 INSERTION_ORDER 类型的资金工具，并表示分配的预算。
credit_remaining_local_micro 适用于 CREDIT_LINE 和 AGENCY_CREDIT_LINE 类型的资金工具。它表示 credit_limit_local_micro 减去该资金工具已花费的金额。它不表示 funded_amount_local_micro 与已花费金额之间的差额。我们区分信用限额与分配资金，是因为它们代表了我们与广告主采用的不同底层资金方式和支出协议。
资金工具类型
CREDIT_LINE 类型）。
定位
按投放位置的定位选项
- X Search：Age Targeting、Devices、Events、Gender、Keyword Types (All)、Language、Locations、Network Activation、Network Operators、Platform、Platform Version、Tailored Audiences、WiFi Only
- X Timeline：Age Targeting、Devices、Events、Followers Of、Similar to Followers Of、Gender、Interest、Language、Locations、Network Activation、Network Operators、Non-exact Keyword Types、Partner Audience Types、Platform、Platform Version、Retargeting Types、Tailored Audiences、TV Targeting Types、WiFi Only
- X Profiles & Tweet Details：Age Targeting、Devices、Events、Followers Of、Similar to Followers Of、Gender、Interest、Language、Locations、Network Activation、Network Operators、Non-exact Keyword Types、Partner Audience Types、Platform、Platform Version、Retargeting Types、Tailored Audiences、TV Targeting Types、WiFi Only
了解定位类型
NETWORK_OPERATOR。
New Mobile Device Targeting：根据用户首次通过设备访问 X 的日期定位用户，使用定位类型 NETWORK_ACTIVATION_DURATION，使用 operator_type 为 LT 表示小于，以及 GTE 表示大于或等于。
Platforms、Platform Versions、Devices 和 Wifi-Only：允许通过多种维度定位移动设备。Platforms 是一种高级定位类型，可以针对手机的广泛类别。例如值包括 iOS 和 Android。Devices 允许您定位特定移动设备的用户，例如 iPhone 5s、Nexus 4 或 Samsung Galaxy Note。Platform versions 允许您定位特定移动操作系统的版本用户，直至点版本。示例包括 iOS 7.1 和 Android 4.4。Wifi-Only 允许您仅定位那些使用 WiFi 网络的设备用户；如果未设置此选项，则会定位使用运营商连接以及 WiFi 的用户。
- 用户可以在没有重叠的情况下定位平台和设备。我可以同时将 Blackberry 作为平台和 iPad Air 作为设备进行定位。
- 用户可以同时定位设备和 OS 版本。我可以定位 iPad Air 和 iOS >= 7.0。
- 用户不能定位比设备更广泛的平台。我不能同时定位 iOS 和 iPad Air。
TV_SHOW 定向类型配置，在广告活动运行期间持续生效。使用 GET targeting_criteria/tv_markets 和 GET targeting_criteria/tv_shows 端点来确定可用的电视节目。
Tweet 互动者再定向
Tweet 互动者再定向可让广告主跨设备针对之前曝光或互动过其推广或有机 Tweet 的受众。在 X 上，此定向可让广告主跟进那些曝光或互动过广告主内容的人，这些人最有可能对后续消息或优惠进一步互动或转化。用户在曝光或互动后几分钟内即可符合定向资格，此后互动资格可保持长达 90 天，曝光资格为 30 天。
Tweet 互动者定向类型：
ENGAGEMENT_TYPE接受IMPRESSION或ENGAGEMENT作为定向值。这指定您希望针对曝光用户（IMPRESSION）还是互动用户（ENGAGEMENT）。CAMPAIGN_ENGAGEMENT使用活动 ID 作为定向值。针对与该活动互动或曝光的用户（取决于ENGAGEMENT_TYPE）。USER_ENGAGEMENT使用推广用户 ID 作为定向值，针对曝光或互动过广告主有机内容的用户（取决于ENGAGEMENT_TYPE）。这必须是与 Ads 账户关联的推广用户 ID。
ENGAGEMENT_TYPE 是必需的，此外还需至少一个有效的 CAMPAIGN_ENGAGEMENT 或 USER_ENGAGEMENT 值。两种 Tweet 互动者定向类型可同时使用，且可在单个行项目中针对多个活动。
视频观看者定向：视频观看者定向基于 Tweet 互动者再定向，可让广告主针对之前在 X 上观看视频部分或全部内容的受众。广告主可针对有机视频、推广视频或两者。推广视频不受限于视频观看目标活动或行项目。
视频观看者定向类型：
VIDEO_VIEW针对点击播放视频或观看 3 秒自动播放的用户VIDEO_VIEW_PARTIAL针对观看视频 50% 的用户VIDEO_VIEW_COMPLETE针对观看至少 95% 视频的用户
ENGAGEMENT_TYPE 时，行项目的定向标准中还必须包含以下一个或两个：
CAMPAIGN_ENGAGEMENT使用活动 ID 作为定向值。针对该活动中观看视频的用户（基于ENGAGEMENT_TYPE）。USER_ENGAGEMENT使用推广用户 ID 作为定向值，针对在广告主有机内容中观看视频的用户（基于ENGAGEMENT_TYPE）。这必须是与 Ads 账户关联的推广用户 ID。
- Broad（默认值）：匹配所有词语，无论顺序。不区分大小写、单复数或时态。当可能时会自动扩展（例如，“car repair” 也会匹配 “automobile fix”）。如果希望不扩展，则需在关键词前添加 + 号，例如 “+boat +jet”。不带 + 的关键词将默认使用 Broad Match。
- Unordered（已弃用）：匹配所有词语，无论顺序。不区分大小写、单复数或时态。
- Phrase：匹配关键词的确切短语，其他词可出现。
- Exact：精确匹配关键词短语，不包含其他词。
- Negative：避免匹配包含这些关键词（无论顺序如何，即使有其他词）的搜索查询。
- Negative Phrase：避免匹配包含此确切关键词短语（即使有其他词）的搜索查询。
- Negative Exact：避免匹配精确匹配这些关键词且不包含其他词的搜索查询。
定向标准组合
| “主要”类型 | 其他类型 |
| 粉丝 | 位置 |
| 定制受众 | 性别 |
| 兴趣 | 语言 |
| 关键词 | 设备和平台 |
| TV | 年龄 |
- “主要”定向类型将进行 ∪（即逻辑并集）。
- 其他定向类型将进行 AND。
- 相同类型将进行 OR。
- 美国、英格兰和加拿大的 X 用户（位置）
- 女性（性别）
- 来自定制受众列表（“主要”）
- 带有关键词（“主要”）
其他示例
- 选择性别和地理位置，但无主要类别：(Male) AND (US OR GB)
- 选择性别、地理位置、兴趣：(Female) AND (CA) AND (Computers OR Technology OR Startups)
- 选择性别、地理位置、兴趣、定制受众、关键词：(Male) AND (GB) AND (Cars ∪ Tailored Audiences for CRM ∪ autocross)
预算投放节奏
standard_delivery 参数设置为 false，以将投放节奏设置为加速投放（请参阅 GET accounts/:account_id/campaigns）。
注意事项
- “Day” 对应 X 广告主账户 的时区（例如 America/Los_Angeles）。
- 早期结果表明，标准投放将改善广告主的 eCPE/CPF，并提供全天更一致的覆盖率。
目标出价
广告系列管理出价策略
| 广告活动目标 | 遗留 | Ads API v10+ |
| 应用安装 | bid_type= AUTObid_unit = APP_INSTALLScharge_by = APP_CLICKS | goal = APP_INSTALLSbid_strategy = AUTO |
| 网站点击 | bid_type = TARGET （注意：对于某些广告活动目标，bid_unit 不需要） | bid_strategy = TARGET |
目标竞价
bid_strategy 设置可以设置为 TARGET 值，以在相关广告系列目标上启用目标竞价，例如：
WEBSITE_CLICKSWEBSITE_CONVERSIONSAPP_INSTALLSAPP_ENGAGEMENTSREACH
国家定向和展示要求
俄罗斯
合作伙伴管理的资金工具
合作伙伴初始设置
- 合作伙伴必须共享其 PGP/GPG 公钥。 需要在 Ads API 合作伙伴和 X 之间交换共享密钥。此密钥将用于在入驻流程中验证数据。
- 用于 Ads API 访问的 X 应用 的
app_id或consumer_secret。 如果您已登录 developer.x.com 上的 X 帐户，则可以通过 应用仪表板 查看和编辑现有 X 应用。如果需要创建 X 应用，则需要拥有已批准的 开发者帐户。X 允许一个用于生产+沙箱的应用，以及一个可选的仅用于沙箱访问的应用。X 应用必须在公司、合作伙伴控制的 X 账号上创建。
广告主入驻流程
- 用户在合作伙伴网站上启动入驻流程，并输入要入驻的 X 账号。
- 合作伙伴将用户重定向到 ads.x.com 上的一个 URL，并附带一个已签名的负载。此负载包含合作伙伴的 API
app_id、要入驻的 X 账号的 Xuser_id、回调 URL 以及下面记录的其他字段。 - 用户被要求使用标准的 x.com 登录页面登录 ads.x.com。
- 用户登录后，即启动入驻流程。此步骤包括广告审核、账户验证和其他检查。
- 当所有入驻任务完成时，用户将被重定向到 Ads API 合作伙伴提供的回调 URL，并附带一个指示成功或失败的负载。此过程包括三腿授权流程。
入门重定向负载
| 名称 | 类型 | 说明 |
| callback_url | URL 编码字符串 | 无论结果如何，账户关联流程完成后，用户都会被重定向到此 URL。协议详情请参见合作伙伴重定向 URL 部分 |
| client_app_id | integer | X API 客户端应用 id，用于识别管理方合作伙伴 |
| promotable_user_id | integer | 其推广将由管理方合作伙伴管理的 @handle 对应的 X user_id。用于确保其与登录 ads.x.com 完成关联流程的用户一致 |
| fi_description | URL 编码字符串（最多 255 个字符） | 资金工具名称。检索资金工具时将显示在 API 的描述字段中。如果提供了 funding_instrument 的描述，现有的 funding_instrument 将被暂停，并将创建新的由合作伙伴管理的资金工具。（如果已存在同名项，则不会发生任何更改） |
| timezone | 字符串（Area/Location 格式） | 用于确定每日预算适用日期并汇总费用的时区 |
| currency | ISO 4217 货币代码 | 用于出价输入与计费的货币 |
| country | ISO 3166-1 alpha-2 国家代码 | 账户的账单国家/地区 |
| signature | URL 编码、base64 编码的二进制值，详见下文 | 使用共享密钥与其他参数生成的签名，用于验证调用的真实性及参数的有效性。 |
回调 URL 载荷
| 名称 | 类型 | 说明 |
| status | string | OK 已创建账户，或找到现有且符合条件的账户。 ACCOUNT_INELIGIBLE 未满足合作伙伴特定约束 USER_MISMATCH 用于登录 ads.x.com 的 X 账户与账户链接请求中的 promotable_user_id 不一致 INCOMPLETE_SERVING_BILLING_INFO 未指定时区、货币或国家/地区 INVALID_COUNTRY 提供了无效的国家/地区值 INVALID_CURRENCY 提供了无效的货币值 INVALID_TIMEZONE 提供了无效的时区值 |
| account_id | URL 编码的字符串 | 已链接账户的 X 广告账户 id |
| funding_instrument_id | URL 编码的字符串 | 活跃的、由合作伙伴管理的资金工具 ID |
| signature | 如下所述的 URL 编码、base64 编码的二进制数据 | 采用 Base64 编码的 HMAC-SHA1 签名，将共享密钥与其他参数组合，用于验证调用的真实性以及参数的有效性。为确保回调 URL 仅对账户链接流程所对应的 X user_id 有效，签名请求时应将 X user_id 使用 & 追加到共享密钥后。 |
user_id 有效，签名请求时，应将 X user_id 使用 & 追加到共享密钥后。
对请求与回调 URL 进行签名
/link_managed_account 的请求和回调 URL 有效，请求需要在源端进行签名，并在接收方采取操作前由接收方进行验证。使用在 X 与托管合作伙伴之间共享的密钥对请求进行签名，可确保双方只接受由授权对方发送的请求。
签名生成算法与 OAuth 所使用的算法类似。
按如下方式创建签名基字符串：
- 将 HTTP 方法转换为大写，并将基字符串设为该值。
- 向基字符串追加“&”字符。
- 对 URL（不含参数）进行百分号编码，并将其追加到基字符串。
- 向基字符串追加“&”字符。
- 追加百分号编码的查询字符串，其构建方式如下：
- 对将被签名的每个键和值进行百分号编码。
- 按键的字母顺序对参数列表进行排序。
- 对每个键/值对（以及用于合作伙伴重定向 URL 的 primary_promotable_user_id）：
- 将百分号编码后的键追加到查询字符串。
- 向基字符串追加“=”字符。
- 将百分号编码后的值追加到查询字符串。
- 使用“&”字符分隔百分号编码后的 key=value 对。
- 使用 HMAC-SHA1 算法，以前面已交换的共享密钥为 key、以基字符串为 value 生成签名。
- 对第 2 步的输出进行 Base64 编码，去掉末尾换行符，对第 3 步生成的签名进行百分号编码，并以 signature 参数的形式将其添加到 URL 中
签名示例
KBxQMMSpKRrtg9aw3qxK4fTXvUc=
随后将该签名（百分号编码后）以 signature 参数的形式添加到原始 URL 末尾（步骤 4）：
https://ads.x.com/link_managed_account?callback_url=https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&client_app_id=12345&fi_description=some%20name&promotable_user_id=1&signature=KBxQMMSpKRrtg9aw3qxK4fTXvUc%3D
为合作伙伴重定向 URL（账户链接请求回调）进行签名 要签名的 URL，假设为 GET 请求：
https://managingpartner.com/link_account_callback?status=OK&account_id=ABC&funding_instrument_id=DEF
此 URL 包含以下参数：
account_id = ABC，funding_instrument_id = DEF，以及 status = OK
由 HTTP 方法和不带参数的 URL 组成的基字符串（步骤 a - d）如下：
GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&“
由步骤 e 的子步骤生成的查询字符串如下：
account_id=ABC&funding_instrument_id=DEF&status=OK
百分号编码后的查询字符串如下：
account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK
完整的基字符串（将步骤 a - d 与 e 组合）：
GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK
使用 hmac-sha1 算法，我们将使用“secret”以及为其发起原始链接请求的 X 用户 id（1，见上文 promotable_user_id = 1）作为密钥，即“secret&1”。
结果进行 Base64 编码，并去掉末尾的“\n”（步骤 2 和 3）：jDSHDkHJIFXpPLVxtA3a9d4bPjM=
然后将此签名（经过百分比编码）添加到原始 URL 的末尾，作为 signature 参数（步骤 4）：
https://managingpartner.com/link_account_callback?&status=OK&account_id=ABC&funding_instrument_id=DEF&signature=jDSHDkHJIFXpPLVxtA3a9d4bPjM%3D
签名算法应支持使用多个密钥重复执行。这将允许使用多个共享密钥，并实现共享密钥的定期轮换。
partner_managed_funding_instrument creation
如果提供了 fi_description 参数，且账户中不存在同名的 partner_managed_funding_instrument，则将创建一个新的 partner_managed_funding_instrument，并暂停所有现有的 partner_managed_funding_instruments。 如果账户中存在同名的 partner_managed_funding_instrument，则不会创建新的 partner_managed_funding_instrument。可重复的引导流程调用 / 令牌刷新
不可重定向的错误流程
对 PMFI 的持续更新
展示位置
placements 参数进行设置。可选值包括：
ALL_ON_TWITTERPUBLISHER_NETWORKTWITTER_PROFILETWITTER_SEARCHTWITTER_TIMELINESPOTLIGHTTREND
product_type 和 objective 决定可用的展示位置。可使用 GET line_items/placements 端点获取各产品类型对应的有效展示位置选项。
此外，下表列出了有效的展示位置与投放目标的组合。
| 目标 | ALL_ON_TWITTER | TWITTER_PROFILE | TWITTER_SEARCH | TWITTER_TIMELINE |
|---|---|---|---|---|
APP_ENGAGEMENTS | ✔ | ✔ | ✔ | ✔ |
APP_INSTALLS | ✔ | ✔ | ✔ | ✔ |
REACH | ✔ | ✔ | ✔ | ✔ |
FOLLOWERS | ✔ | ✔ | ✔ | ✔ |
ENGAGEMENTS | ✔ | ✔ | ✔ | ✔ |
VIDEO_VIEWS | ✔ | ✔ | ✔ | ✔ |
PREROLL_VIEWS | ✔ | ✔ | ✔ | ✔ |
WEBSITE_CLICKS | ✔ | ✔ | ✔ | ✔ |
TWITTER_PROFILE 展示位置。
注意：TWITTER_SEARCH 需要关键词定向。
注意：REACH 目标必须包含 TWITTER_TIMELINE 展示位置。可选择 ALL_ON_TWITTER、任意包含 TWITTER_TIMELINE 的展示位置组合，或仅选择 TWITTER_TIMELINE。
广告组常见问题解答
什么是广告组？
我们如何创建广告组？
为什么我们应该为广告组添加支持？
在广告组（Ad Groups）推广活动中，分项（line item）预算与推广活动预算之间有什么关系？
广告组是否比单个 Line Item 表现更好？
指南
视频观看前贴片目标
所需端点
- 分块媒体上传（用于上传视频）
- POST accounts/:account_id/media_library（将视频关联到广告账户）
- POST accounts/:account_id/campaigns（创建广告系列）
- GET content_categories（获取内容类别与 IAB 类别的对应关系）
- GET accounts/:account_id/curated_categories
- GET publishers
- POST accounts/:account_id/line_item_curated_categories
- POST accounts/:account_id/line_items（创建广告组）
- POST accounts/:account_id/media_creatives（将视频关联到广告组）
- POST accounts/:account_id/preroll_call_to_action（设置 CTA 与重定向 URL）
- POST batch/accounts/:account_id/targeting_criteria（目标定向）
步骤
上传视频
上传视频媒体
INIT 请求中传递 media_category=amplify_video。你将以分块方式上传视频。当 STATUS 返回的 state 为 succeeded 后，即可继续下一步。关于使用分块端点上传媒体的更多信息，请参阅我们的推广视频概览。
将视频添加到广告账户
STATUS 命令返回的状态为 succeeded 时，使用该端点返回的 media_key 通过 POST accounts/:account_id/media_library 端点将视频添加到广告主的媒体库。
设置广告活动
活动创建
objective应设为VIDEO_VIEWS_PREROLL，product_type设为MEDIA。同时必须将categories参数设置为相应的广告主业务类别。
创建 Line Item
categories 参数设置为 “Science & Education”，必须为该广告项目设置完整的 iab_categories 集合，即 "IAB5", "IAB15"，如下所示：
发布者选择
精选类别
- 投放单需根据精选类别的 country_code 定向到相应的国家/地区
- 必须使用 POST line_item_curated_categories 端点，将投放单与特定的 curated_category_id 关联。
内容类别
注意：必须通过定向条件端点对 GET curated_categories 响应中的完整 iab_categories 集合进行定向，否则会产生验证错误。
将账号媒体（视频）关联到广告组项
设置 CTA 和目标 URL
VIDEO_VIEWS_PREROLL 目标不使用 Promoted Tweet 或 Card。相反，视频创意与您的广告组（line item）关联，而 CTA 信息与 preroll_call_to_action 实体关联。POST accounts/:account_id/preroll_call_to_action 端点可用于设置按钮 CTA 和目标 URL。
设置定向条件
CONTENT_PUBLISHER_USER 用作否定定向，以将广告从与特定用户的配对中排除。请提供要排除账号的 X user_id 或 publisher_user_id（对应的账号句柄）。
可以使用 GET publishers 端点获取需在内容分类中排除的 user_id 列表。在 GET curated_categories 响应中返回的 publisher_user_id 可用于获取精选分类的类似排除列表。
注意： 精选分类最多可排除 5 个 publisher_user_id，内容分类最多可排除 50 个 user_id。
启动广告系列
分析
VIDEO_VIEWS_PREROLL 活动的分析数据。
时间线中的关键词定向
它如何运作？
targeting_type 设置为 unordered_keywords 或 phrase_keywords 即可。
快速开始指南
- 创建一个新的 line item，并将投放位置设置为包含
ALL_ON_TWITTER或TWITTER_TIMELINE。 POST accounts/:account_id/line_items - 为新建的 line item 创建定向条件，使用
BROAD_KEYWORD并设置关键词值。 POST accounts/:account_id/targeting_criteria - 你可以通过 PUT accounts/:account_id/targeting_criteria 更新关键词。
- 当广告系列开始运行后，获取该 line item 的统计数据以评估效果。 GET stats/accounts/:account_id
API 参考
账户
https://ads-api.x.com/12/accounts
Parameters
| Name | Description |
|---|---|
| account_ids optional | 通过指定以逗号分隔的标识符列表，仅返回所需的账户 id。 Type: string Example: 18ce54d4x5t |
| count optional | 指定每个请求尝试检索的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。详情参见分页。 Type: string Example: 8x7v00oow |
| q optional | 可选查询，用于按 name 限定资源范围。 Note: 执行不区分大小写的前缀匹配。 Type: string Min, Max length: 1, 255 |
| sort_by optional | 按受支持的属性进行升序或降序排序。详情参见排序。 Type: string Example: created_at-asc |
| with_deleted optional | 在响应中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | 在响应中包含 total_count 属性。 Note: 此参数与 cursor 互斥。 Note: 包含 total_count 的请求将有更低的速率限制，目前为每 15 分钟 200 次。 Type: boolean Default: false Possible values: true, false |
GET accounts/:account_id
获取经身份验证的用户可访问的特定账户。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，除 GET accounts 外，一般是所有 Advertiser API 请求所需的参数。 指定的账户必须与经身份验证的用户关联。 类型：string 示例： 18ce54d4x5t |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值： false 可能的取值： true、false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t
示例响应
https://ads-api-sandbox.x.com/12/accounts
参数
无
示例请求
POST https://ads-api-sandbox.x.com/12/accounts
示例响应
PUT accounts/:account_id
更新账户名称和/或行业类型。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id
参数
| 名称 | 描述 |
|---|---|
| account_id required | 被操作账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。 指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| name optional | 账户名称。 类型：string 示例： API McTestface |
| industry_type optional | 账户所属行业。 类型：string 可能的取值： AGENCY, BUSINESS_TO_BUSINESS, ONLINE_SERVICES, EDUCATION, FINANCIAL, HEALTH, GOVERNMENT, MEDIA, MOBILE, RESTAURANT, RETAIL, TECHNOLOGY, TRAVEL, OTHER |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY
示例响应
DELETE accounts/:account_id
注意：仅限 SANDBOX 在 sandbox 环境中删除广告账户。 Resource URLhttps://ads-api-sandbox.x.com/12/accounts/:account_id
Parameters
| Name | Description |
|---|---|
| account_id required | 目标账户的标识符。该值出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。 指定的账户必须与已通过身份验证的用户关联。 类型：string 示例： 18ce54d4x5t |
DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh
Example Response
账户应用
GET account_apps
获取与指定广告账户关联的所有移动应用的详细信息。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/account_apps
Parameters
| 名称 | 说明 |
|---|---|
| account_id required | 目标账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| count optional | 指定每个请求尝试检索的记录数量。 类型：int 默认值： 200 最小值、最大值： 1、1000 |
| cursor optional | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 类型：string 示例： 8x7v00oow |
| sort_by optional | 按受支持的属性进行升序或降序排序。更多信息参见 Sorting。 类型：string 示例： created_at-asc |
| with_deleted optional | 在请求中包含已删除的结果。 类型：boolean 默认值： false 可能的取值： true、false |
| with_total_count optional | 在响应中包含 total_count 属性。 注意：此参数与 cursor 互斥。 注意：包含 total_count 的请求其速率限制更低，目前为每 15 分钟 200 次。 类型：boolean 默认值： false 可能的取值： true、false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps
Example Response
账户历史记录
GET accounts/:account_id/account_history
检索请求中指定的entity_id 的变更摘要。
注意：此端点目前处于测试阶段，需要加入允许名单。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/account_history
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标（被管理）账号的标识符。 类型：string 示例： 18ce54d4x5t |
| count 可选 | 指定每次请求尝试检索的记录数量。 类型：int 默认值： 200 最小/最大： 1，1000 |
| cursor 可选 | 用于获取下一页结果的游标。详见分页。 类型：string 示例： 8x7v00oow |
| entity_type 必填 | 要检索 data 的实体类型。 类型：enum 示例： PROMOTED_TWEET 可能的取值： CAMPAIGN、LINE_ITEM、PROMOTED_TWEET、TARGETING_CRITERIA、PROMOTED_ACCOUNT |
| entity_id 必填 | 要检索 data 的具体实体。 类型：string 示例： 8u94t |
| start_time 必填 | 将检索的数据限定为指定的开始时间，使用 ISO 8601 表示。 注意：必须为整点（0 分钟 0 秒）。 类型：string 示例： 2017-05-19T07:00:00Z |
| end_time 必填 | 将检索的数据限定为指定的结束时间，使用 ISO 8601 表示。 注意：必须为整点（0 分钟 0 秒）。 类型：string 示例： 2017-05-26T07:00:00Z |
| user_id 可选 | 将响应限定为特定用户。 类型：long 示例： 3271358660 |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1
示例响应
广告主业务类别
GET advertiser_business_categories
请求用于向发布方描述广告主品牌的广告组（line_items）可用的有效广告主营业 categories。
注意：这些类别仅适用于目标为 PREROLL_VIEWS 的 line_items，并且与用于定向条件的 content_categories 相互独立。
每个 advertiser_business_categories 表示一组 IAB 类别。当以 PREROLL_VIEWS 为目标创建广告组时，必须为该广告组设置一到两个 advertiser_business_categories。可通过在 line item 端点的请求参数 categories 中设置相应的 iab_categories 集合来完成，该集合可通过此端点获取。
更多详情参见 Video Views Preroll Objective Guide
Resource URL
https://ads-api.x.com/12/advertiser_business_categories
Parameters
无请求参数
Example Request
GET https://ads-api.x.com/12/advertiser_business_categories
Example Response
受众估算
估算广告活动的受众规模。
Content-Type: application/json 头。
注意：必须至少指定一个“主要”定向条件；可在我们的广告活动定向页面查看所有主要定向条件的列表。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/audience_estimate
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被使用的账户标识符。出现在资源路径中，并且通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| targeting_criteria 必填 | 一个包含所有定向条件对象参数的 JSON 对象。必填和可选的定向条件参数列表见 POST accounts/:account_id/targeting_criteria 端点。 |
| operator_type 可选 | 指定定向条件之间的关系。例如，要设置排除性定向，请使用 operator_type=NE。类型：enum 可选值： EQ、NE默认值： EQ |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate
认证用户访问
GET accounts/:account_id/authenticated_user_access
检索当前已通过身份验证的用户（access_token）在指定广告账户中的权限。这些权限与 ads.x.com 上展示的权限一致。 可能的取值包括：ACCOUNT_ADMIN：可完全修改广告系列并查看统计数据，且可添加或移除用户、变更设置AD_MANAGER：可完全修改广告系列并查看统计数据，但不可添加或移除用户或变更设置CREATIVE_MANAGER：可修改创意并查看预览，但不可创建或修改广告系列CAMPAIGN_ANALYST：可查看广告系列和统计数据，但不可创建或修改广告系列ANALYST（在 ads.x.com 上为“Organic Analyst”）：可查看自然数据分析和受众洞察，但不可创建、修改或查看广告系列PARTNER_AUDIENCE_MANAGER：仅限 API 的访问权限，可查看和修改数据合作伙伴受众，但不可访问广告系列、创意或其他受众类型。
TWEET_COMPOSER 权限表示该已认证用户可代表广告主创建未投放（或“仅推广”）的 Tweets。仅适用于拥有 ACCOUNT_ADMIN、AD_MANAGER 或 CREATIVE_MANAGER 访问权限的用户。
Resource URL
https://ads-api.x.com/12/accounts/:account_id/authenticated_user_access
Parameters
无
Example Request
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/authenticated_user_access
Example Response
出价规则
GET bidding_rules
检索指定或全部货币的竞价规则。响应将给出 CPE（每次互动成本）出价的最小值和最大值。 尽管这些竞价规则很少变化，建议你的系统至少每月从这些端点进行一次刷新。 资源 URLhttps://ads-api.x.com/12/bidding_rules
参数
| 名称 | 描述 |
|---|---|
| currency 可选 | 用于按货币筛选结果，采用 ISO-4217 标识。为三字母字符串“USD”或“EUR”。省略此参数可检索所有竞价规则。 类型：string 示例： USD |
GET https://ads-api.x.com/12/bidding_rules?currency=USD
示例响应
活动
GET accounts/:account_id/campaigns
检索与当前账户关联的部分或全部广告系列的详细信息。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns
Parameters
| Name | Description |
|---|---|
| account_id required | 使用的账户标识符。它出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| campaign_ids optional | 通过提供用逗号分隔的标识符列表，仅返回所需的广告系列。最多可提供 200 个 ID。 Type: string Example: 8wku2 |
| count optional | 指定每次请求尝试检索的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string Example: 8x7v00oow |
| funding_instrument_ids optional | 通过提供用逗号分隔的标识符列表，仅返回隶属于特定资金工具的广告系列。最多可提供 200 个 ID。 Type: string Example: lygyi |
| q optional | 可选查询，用于按 name 过滤资源。Type: string Min, Max length: 1, 255 |
| sort_by optional | 按受支持的属性进行升序或降序排序。更多信息参见 Sorting。 Type: string Example: created_at-asc |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
| with_draft optional | 在请求中包含草稿广告系列的结果。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | 在响应中包含 total_count 属性。Note: 此参数与 cursor 互斥。Note: 包含 total_count 的请求将有更低的速率限制，目前为每 15 分钟 200 次。Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2
Example Response
GET accounts/:account_id/campaigns/:campaign_id
获取与当前账户关联的特定广告系列。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id
参数
| Name | Description |
|---|---|
| account_id required | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| campaign_id required | 在请求中所操作的广告系列的引用。 Type: string Example: 8wku2 |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2
示例响应
POST accounts/:account_id/campaigns
创建与当前账户关联的新广告系列。 注意：每个账户默认最多可有 200 个启用中的广告系列。但未启用的广告系列数量不受限制。该上限可提升至 8,000 个启用中的广告系列。如需启用更高上限，广告主须向其 X 客户经理提出申请。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，并且通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| funding_instrument_id 必填 | 要在其下创建广告系列的资金工具标识符。 类型：string 示例： lygyi |
| name 必填 | 广告系列名称。最大长度：255 个字符。 类型：string 示例： demo |
| budget_optimization 可选 | 选择要应用的预算优化类型。 类型：enum 默认值： CAMPAIGN 可能的取值： CAMPAIGN、LINE_ITEM |
| daily_budget_amount_local_micro 有时必填 | 分配给广告系列的每日预算金额。将使用与指定资金工具关联的货币。以 USD 为例，$5.50 表示为 5500000。 注意：该值应小于或等于 total_budget_amount_local_micro，且对大多数资金工具类型为必填项。类型：long 示例： 5500000 |
| entity_status 可选 | 广告系列状态。 类型：enum 默认值： ACTIVE 可能的取值： ACTIVE、DRAFT、PAUSED |
| purchase_order_number 可选 | 预订参考编号。使用此字段助力发票对账。最大长度：50 个字符。 类型：string 示例： D00805843 |
| standard_delivery 可选 | 启用标准或加速投放。有关标准与加速投放的更多信息，请参见 Budget Pacing。仅当 budget_optimization 设置为 CAMPAIGN 时可用。类型：boolean 默认值： true 可能的取值： true、false |
| total_budget_amount_local_micro 可选 | 分配给广告系列的总预算金额。将使用与指定资金工具关联的货币。以 USD 为例，$37.50 表示为 37500000。 类型：long 示例： 37500000 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&daily_budget_amount_local_micro=140000000&entity_status=PAUSED&budget_optimization=CAMPIAGN&standard_delivery=false
示例响应
POST batch/accounts/:account_id/campaigns
允许通过单个请求批量创建新的广告系列。 批量请求- 当前最大批处理大小为 40。
- 所有参数通过请求正文发送，并且必须将
Content-Type设置为application/json。 - 批量请求以整体方式共同成功或失败，且无论成功或失败，所有 API 响应都会保留与初始请求一致的项目顺序。
- 请求级错误（如超出最大批处理大小）会在响应中的
errors对象下返回。 - 项目级错误（如缺少必填广告系列参数）会在响应中的
operation_errors对象下返回。
https://ads-api.x.com/12/batch/accounts/:account_id/campaigns
参数
| 名称 | 描述 |
|---|---|
| operation_type 必填 | 针对每个项目要执行的操作类型。 类型：枚举 可选值： Create、Delete、Update |
| params 必填 | 一个包含广告系列对象全部参数的 JSON 对象。有关广告系列必填与可选参数列表，请参见此处。 |
POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns
PUT accounts/:account_id/campaigns/:campaign_id
更新当前账户下的指定广告系列。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| campaign_id 必填 | 本次请求中要操作的广告系列标识。 类型：string 示例： 8wku2 |
| budget_optimization 可选 | 选择要应用的预算优化类型。 类型：enum 默认值： CAMPAIGN 可能的取值： CAMPAIGN、LINE_ITEM |
| daily_budget_amount_local_micro 可选 | 分配给广告系列的每日预算金额。将使用与指定资金工具关联的货币。对于 USD，$5.50 表示为 5500000。未提供时，广告系列将基于总预算并在投放期间均匀消耗。 注意：该值应小于或等于 total_budget_amount_local_micro。类型：long 示例： 5500000 |
| entity_status 可选 | 广告系列状态。 类型：enum 可能的取值： ACTIVE、PAUSED |
| name 可选 | 广告系列名称。最大长度：255 个字符。 类型：string 示例： demo |
| purchase_order_number 可选 | 订购参考编号。使用此字段辅助对发票进行核对。最大长度：50 个字符。 类型：string 示例： D00805843 |
| standard_delivery 可选 | 启用标准或加速投放。有关标准与加速投放的详情，请参阅 Budget Pacing。仅当 budget_optimization 设置为 CAMPAIGN 时可用。类型：boolean 默认值： true 可能的取值： true、false |
| total_budget_amount_local_micro 可选 | 分配给广告系列的总预算金额。将使用与指定资金工具关联的货币。对于 USD，$37.50 表示为 37500000。 类型：long 示例： 140000000 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000
示例响应
DELETE accounts/:account_id/campaigns/:campaign_id
删除当前账户下指定的广告系列。 注意：删除广告系列不可撤销，之后再次尝试删除该资源将返回 HTTP 404。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id
参数
| Name | Description |
|---|---|
| account_id required | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所必需的参数。指定的账户必须与已验证用户关联。 Type: string Example: 18ce54d4x5t |
| campaign_id required | 本次请求中要操作的广告系列的引用。 Type: string Example: 8yn7m |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m
示例响应
内容分类
GET content_categories
请求用于作为某个 line item 的targeting_criteria 的有效内容 categories。
每个 content_category 对应一个或多个 IAB Categories。可在批量 targeting_criteria 端点将 targeting_type 设置为 IAB_CATEGORY，以包含 content_categories 请求返回的相应 iab_categories 集合。否则会导致验证错误。
可使用 GET publishers 端点获取这些内容类别的发布方详细信息。
更多信息请参见 Video Views Pre-roll Objective Guide。
Resource URL
https://ads-api.x.com/12/content_categories
Parameters
无请求参数
Example Request
GET https://ads-api.x.com/12/content_categories
Example Response
精选分类
GET accounts/:account_id/curated_categories
检索针对给定country_codes 可用的精选类别列表
每个 curated_category 仅在响应中由 country_codes 指定的特定国家/地区可用。
更多详情请参阅 Video Views Pre-roll Objective Guide。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/curated_categories
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，并且通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| country_codes 必填 | 通过指定以逗号分隔的两字母 ISO 国家/地区代码列表，将响应限定在所需国家/地区范围内。最多可提供 200 个代码。 类型：string 示例： US |
| cursor 可选 | 指定游标以获取下一页结果。更多信息参见 Pagination。 类型：string 示例： 8x7v00oow |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US
示例响应
GET accounts/:account_id/curated_categories/:curated_category_id
获取特定curated_category_id 的详细信息
每个 curated_category 仅在响应中 country_codes 指定的特定国家/地区可用。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/curated_categories/:curated_category_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，并且通常是除 GET accounts 之外所有 Advertiser API 请求所必需的参数。指定的账户必须与已验证用户关联。 类型：string 示例： 18ce54d4x5t |
| curated_category_id 必填 | 此次请求中所操作的 Curated Category 的标识引用。 类型：string 示例： 9ddrgesiap6o |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o
响应示例
功能
GET accounts/:account_id/features
检索该广告账户可用的已授予功能集合。功能以描述性的功能键标识，且仅在其处于测试版或其他受限发布阶段并已在 Ads API 中提供时，才会在此端点返回。不符合该条件的功能不会通过此端点暴露。 注意：此端点旨在通过提升对客户端测试版访问的可见性，支持 Ads API 生态的开发。API 开发者无法代表广告主申请功能访问。此类申请只能由广告主向其 X 客户经理提出。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/features
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，通常作为除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已通过身份验证的用户关联。 类型：string 示例： 18ce54d4x5t |
| feature_keys 可选 | 可选参数，用于查询特定功能键。请求中可包含多个以逗号分隔的键。 注意：响应仅包含该账户可访问的功能。 类型：enum 可能的取值： REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, WEBSITE_CLICKS_CPM_BILLING |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features
示例响应
POST accounts/:account_id/features
仅限 SANDBOX 向 sandbox 账户添加功能。 可通过 GET accounts/:account_id/features 端点获取最新的账户功能列表。 资源 URLhttps://ads-api-sandbox.x.com/12/accounts/:account_id/features
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，且通常是在除 GET accounts 外所有 Advertiser API 请求中必需的参数。指定的账户必须与已认证用户关联。 类型：string 示例： gq180y |
| feature_keys 必填 | 以逗号分隔的要添加到该账户的功能列表。 类型：enum 可选值： AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD |
POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING
示例响应
DELETE accounts/:account_id/features
仅限 SANDBOX 从 sandbox 账户移除某个功能。 可通过 GET accounts/:account_id/features 端点获取最新的账户功能列表。 资源 URLhttps://ads-api-sandbox.x.com/12/accounts/:account_id/features
参数
| 名称 | 描述 |
|---|---|
| account_id required | 目标账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 类型：string 示例： gq180y |
| feature_keys required | 以逗号分隔的要从该账户移除的账户功能列表。 类型：enum 可能的取值： AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD |
DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE
示例响应
资金工具
GET accounts/:account_id/funding_instruments
检索与当前账户关联的部分或全部资金工具的详细信息。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/funding_instruments
Parameters
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被管理账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| count 可选 | 指定每个请求尝试检索的记录数量。 类型：int 默认值： 200 最小值、最大值： 1, 1000 |
| cursor 可选 | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 类型：string 示例： 8x7v00oow |
| funding_instrument_ids 可选 | 通过指定以逗号分隔的标识符列表，将响应限定为所需的资金工具。最多可提供 200 个 ID。 类型：string 示例： lygyi |
| sort_by 可选 | 按受支持的属性进行升序或降序排序。更多信息参见 Sorting。 类型：string 示例： created_at-asc |
| with_deleted 可选 | 在结果中包含已删除的记录。 类型：boolean 默认值： false 可选值： true, false |
| with_total_count 可选 | 在响应中包含 total_count 属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求具有更低的速率限制，目前为每 15 分钟 200 次。类型：boolean 默认值： false 可选值： true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments
Example Response
GET accounts/:account_id/funding_instruments/:funding_instrument_id
检索与当前账户关联的指定资金工具。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/funding_instruments/:id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 该广告账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| funding_instrument_id 必填 | 请求中所操作的资金工具引用。 类型：string 示例： lygyi |
| with_deleted 可选 | 在响应中包含已删除的结果。 类型：boolean 默认值： false 可选值： true、false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi
示例响应
POST accounts/:account_id/funding_instruments
仅限 SANDBOX 在 sandbox 环境中创建资金工具（Funding Instrument）。 在使用 sandbox 资金工具时不会产生任何费用风险。 资源 URLhttps://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。该值出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例： gq1844 |
| currency 必填 | 货币，遵循 ISO-4217 标准。 类型：string 示例： USD |
| start_time 必填 | 资金工具开始生效并可使用的日期时间，遵循 ISO 8601 标准。 类型：string 示例： 2017-05-19T07:00:00Z |
| type 必填 | 要创建的资金工具类型。 类型：enum 可能的取值： AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED |
| end_time 有时必填 | 资金工具失效的日期时间，遵循 ISO 8601 标准。 类型：string 示例： 2017-05-26T07:00:00Z |
| credit_limit_local_micro 可选 | 此资金工具可用的总信用额度。 注意：仅适用于某些资金工具类型。 类型：long 示例： 37500000 |
| funded_amount_local_micro 可选 | 分配给此资金工具的总预算金额。 注意：仅适用于某些资金工具类型。 类型：long 示例： 37500000 |
POST https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments?currency=USD&start_time=2017-07-10T00:00:00Z&type=INSERTION_ORDER&end_time=2018-01-10T00:00:00Z&funded_amount_local_micro=140000000000
示例响应
DELETE accounts/:account_id/funding_instruments/:funding_instrument_id
仅限 SANDBOX 在 sandbox 环境中删除资助工具。 资源 URLhttps://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被管理账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例： gq1844 |
| funding_instrument_id 必填 | 本次请求中要操作的资助工具的引用。 类型：string 示例： hxt82 |
DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82
示例响应
IAB 分类
GET iab_categories
请求广告组（line_items）可用的应用 categories。
资源 URL
https://ads-api.x.com/12/iab_categories
参数
| 名称 | 描述 |
|---|---|
| count 可选 | 指定每个请求尝试检索的记录数量。 类型：int 默认值： 200 最小值/最大值： 1、1000 |
| cursor 可选 | 指定用于获取下一页分类的游标。更多信息参见 Pagination。 类型：string 示例： gc-ddf4a |
| with_total_count 可选 | 是否在响应中包含 total_count 属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求将受到更低的速率限制，当前为每 15 分钟 200 次。类型：boolean 默认值： false 可选值： true、false |
GET https://ads-api.x.com/12/iab_categories?count=2
示例响应
订单项
GET accounts/:account_id/line_items
检索与当前账户关联的部分或全部投放项的详细信息。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_items
Parameters
| Name | Description |
|---|---|
| account_id required | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有广告主 API 请求必需的参数。指定的账户必须与已验证用户关联。 Type: string Example: 18ce54d4x5t |
| campaign_ids optional | 通过指定以逗号分隔的标识符列表，将响应限定为特定广告系列下的投放项。最多可提供 200 个 ID。 Type: string Example: 8gdx6 |
| count optional | 指定每次请求尝试检索的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。更多信息请参阅 Pagination。 Type: string Example: 8x7v00oow |
| funding_instrument_ids optional | 通过指定以逗号分隔的标识符列表，将响应限定为特定资金工具下的投放项。最多可提供 200 个 ID。 Type: string Example: lygyi |
| line_item_ids optional | 通过指定以逗号分隔的标识符列表，将响应限定为所需的投放项。最多可提供 200 个 ID。 Type: string Example: 8v7jo |
| q optional | 可选查询参数，用于按 name 过滤资源。Type: string Min, Max length: 1, 255 |
| sort_by optional | 按支持的属性进行升序或降序排序。更多信息请参阅 Sorting。 Type: string Example: created_at-asc |
| with_deleted optional | 在响应中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
| with_draft optional | 在响应中包含草稿广告系列的结果。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | 在响应中包含 total_count 属性。Note: 此参数与 cursor 互斥。Note: 包含 total_count 的请求将适用更低的速率限制，目前为每 15 分钟 200 次。Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx
Example Response
GET accounts/:account_id/line_items/:line_item_id
检索与当前账户关联的指定 Line Item。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id
Parameters
| Name | Description |
|---|---|
| account_id required | 被使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求所必需的参数。所指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| line_item_id required | 本次请求中所操作的 Line Item 的引用。 类型：string 示例： 8v7jo |
| with_deleted optional | 在请求中包含已删除的结果。 类型：boolean 默认值： false 可能取值： true、false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx
Example Response
POST accounts/:account_id/line_items
为当前账户下的指定广告系列创建一个关联的行项目。 同一广告系列中的所有行项目必须具有相同的product_type 和 objective。
当使用 PROMOTED_ACCOUNT 产品类型时，将一条 Tweet 关联到该 line_item，除标准的 PROMOTED_ACCOUNT 投放位置外，还会在移动端时间线增加投放位置。
设置 android_app_store_identifier 或 ios_app_store_identifier 任一字段，会自动为行项目添加与所推广移动应用匹配的定向条件；例如，传入 ios_app_store_identifier 将为 iOS 添加 PLATFORM 定向条件。
注意：每个广告系列最多可包含 100 个行项目，且所有广告系列合计最多可有 256 个活跃行项目。
Resource URL
https://ads-api.x.com/12/accounts/:account_id/line_items
Parameters
| 名称 | 说明 |
|---|---|
| 帐户_id 必填项 | 杠杆账户的标识符。显示在该资源中’的路径中，并且通常是所有广告主 API 请求（不包括GET accounts。指定的账户必须与已认证的用户关联。 类型：字符串 示例： 18ce54d4x5t |
| 广告系列_id 必需 | 用于在其下创建该广告组的活动 ID。 类型：字符串 示例： 8slvg |
| 结束_时间 必填项 | 以……形式表示的时间ISO 8601 标准，该订单项将停止投放。 类型：字符串 示例： 2017-10-05T00:00:00Z |
| 目标 必填项 | 此行项目的投放目标。 类型：枚举 可能的值： APP_ENGAGEMENTS，APP_INSTALLS，触达，关注者，互动量，VIDEO_VIEWS，PREROLL_VIEWS，WEBSITE_CLICKS |
| 投放版位 必填项 | 此订单项的展示位置。请指定以逗号分隔的投放位置值列表。 类型：枚举 可能的值： ALL_ON_TWITTER，PUBLISHER_NETWORK，TAP_BANNER，TAP_FULL，TAP_FULL_LANDSCAPE，TAP_NATIVE，TAP_MRECT，TWITTER_PROFILE，TWITTER_REPLIES，TWITTER_SEARCH，TWITTER_TIMELINE |
| 产品_类型 必填 | 此订单项包含的推广产品类型。 类型：枚举 可能的值： 媒体，PROMOTED_ACCOUNT，PROMOTED_TWEETS |
| 开始_时间 必填项 | 以……表示的时间ISO 8601 标准，该广告项将开始投放。 类型：string 示例： 2017-07-05T00:00:00Z |
| 广告主_域名 有时必需 | 此广告主的网站域名（不含协议部分）。 注意事项：当该订单项时为必填’其投放位置设置为 PUBLISHER_NETWORK。类型：字符串 示例： x.com |
| Android_应用_存储_标识符 有时需要 | 用于投放推广的应用在 Google Play 商店中的标识符。 注意: APP_INSTALLS及APP_ENGAGEMENTS目标需要至少设置一个应用商店标识符——可选择 android_app_store_identifier 或 ios_app_store_identifier 之一android_app_store_identifier或ios_app_store_identifier。类型：字符串 示例： com.twitter.android |
| 出价_金额_本地_微型 有时为必填 | 要与此订单项关联的出价金额。将使用与指定资金工具所对应的货币。对于 USD，$5.50 表示为 5,500,000。 注意事项：在以下情况下为必填 bid_strategy被设置为以下任一项MAX或目标注意: 仅接受大于零的值。 类型：long 示例： 5500000 |
| 分类 有时必需 | 与该广告主相关的 IAB 类别。参见GET iab_categories。 注意事项：当投放项时必填’的展示位置设置为 PUBLISHER_NETWORK。类型：字符串 示例： IAB3-1 |
| iOS_应用_存储_标识符 有时为必填项 | 用于推广应用的 Apple App Store 标识符的数字部分。 注意事项: APP_INSTALLS和APP_ENGAGEMENTS目标必须设置至少一个应用商店标识符——可以是android_app_store_identifier或ios_app_store_identifier。类型：字符串 示例： 333903271 |
| 主要_Web_事件_标签 有时为必填项 | 主要网页事件标签的标识符。可更准确地跟踪与此行项目相关的广告活动互动。 注意：当此广告项（line item）‘的目标已设置为 WEBSITE_CONVERSIONS。类型：字符串 示例： nvo4z |
| 广告主_用户_id 可选项 | 用于推广的帐号之 X 用户标识符PREROLL_VIEWS广告。只有特定的客户端应用可以使用此参数。类型：字符串 示例： 312226591 |
| 目标受众_扩展字段 可选 | 通过定位与现有目标受众相似的用户来扩大广告系列的触达范围。 注意: 默认情况下，不会应用任何展开。 类型：枚举类型 可能的值： 广泛，已定义，展开 |
| 出价_战略 可选 | 竞价机制。自动将根据每日预算和广告活动的投放周期自动优化出价。MAX设置可接受的最高出价，并且否在目标设置为时可用覆盖人数或关注者。TARGET尝试将每日出价均值控制在所设定值的20%范围内bid_amount_local_micro且当目标设为覆盖人数,关注者，或WEBSITE_CLICKS。注意：如果设置为 自动，bid_amount_local_micro将被忽略。注意：默认设置取决于目标。 类型：枚举 可能的值： 自动，MAX,目标 |
| 时长_在_天数 可选（选填） | 在其内的时间期限frequency_cap已实现。类型：int 可能的值： 1，7，30 |
| 实体_状态 可选 | 广告项目条目的状态。 类型：枚举 默认： 活动 可能的值： ACTIVE，草稿，暂停 |
| 频率_上限 可选 | 某广告可向单个用户投放的最大次数。 注意: 仅适用于 触达，互动，VIDEO_VIEWS，和PREROLL_VIEWS目标。类型：int 示例： 5 |
| 目标 可选项 | 用于该明细项的优化设置。 The APP_PURCHASES可用于APP_INSTALL。TheAPP_CLICKS及APP_INSTALLS两者均可用选项APP_INSTALL与APP_ENGAGEMENTS目标，并且可能需要使用受支持的MACT 合作伙伴。The SITE_VISITS该选项仅在以下情况下可用WEBSITE_CLICKS目标。注意事项：默认值取决于目标。 类型：枚举型 可能的值： APP_CLICKS，APP_INSTALLS，APP_PURCHASES，互动量,粉丝，LINK_CLICKS，MAX_REACH，前贴片,PREROLL_STARTS，REACH_WITH_ENGAGEMENT，SITE_VISITS，VIDEO_VIEW，VIEW_3S_100PCT，VIEW_6S，VIEW_15S，WEBSITE_CONVERSIONS |
| 名称 可选项 | 广告项目（line item）的名称。 类型：字符串 示例： 演示最小/最大长度： 1，255 |
| 支付_由 可选项 | 用于对此行项目计费的单位。只有当此行项目使用APP_INSTALLS目标。注意：默认设置 pay_by会根据广告系列目标和订单项自动设置’的竞价单位。The APP_INSTALLS目标同时支持这两种方式APP_CLICK和IMPRESSION数值。IMPRESSION为默认值。The LINK_CLICKS目标同时支持二者链接点击和展示次数数值。展示是默认值，但在设置时不受支持TARGET用于bid_strategy。The SITE_VISITS支持的目标曝光数值。类型：枚举 可能的值： APP_CLICK，展示，LINK_CLICK |
| 标准_投放 可选 | 启用标准或加速投放。请参阅预算投放节奏了解标准投放与加速投放的更多信息。仅在budget_optimization设置为LINE_ITEM针对上级广告系列类型：布尔值 默认： true 可能的值： true,false |
| 总数_预算_金额_本地_微型 可选项 | 分配给该线项的总预算金额。将使用与指定资金工具关联的货币。对于 USD，$37.50 表示为 37500000。 类型：long 示例： 37500000 |
| 每天_预算_金额_本地_微型 有时必需 | 要分配给广告系列的每日预算金额。将使用与指定资金工具关联的货币。对于 USD，$5.50 表示为 5500000。若未提供，广告系列将根据总预算并在投放期间均匀消耗。仅当父广告系列的 budget_optimization 设置为 LINE_ITEM 时可用budget_optimization设置为LINE_ITEM针对父级广告系列注意：应小于或等于 total_budget_amount_local_micro。类型：long 示例： 5500000 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?campaign_id=hwtq0&objective=ENGAGEMENTS&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&bid_amount_local_micro=3210000&entity_status=PAUSED&daily_budget_amount_local_micro=1000000&start_time=2022-06-15
示例响应
POST batch/accounts/:account_id/line_items
允许通过单个请求批量创建新的广告项。 批量请求- 目前最大批量大小为 40。
- 所有参数通过请求正文发送，且必须将
Content-Type设置为application/json。 - 批量请求作为一个整体同时失败或成功，对应的所有 API 响应（无论成功或错误）都会保留初始请求中的项目顺序。
- 请求级错误（例如超出最大批量大小）会在响应的
errors对象下显示。 - 项目级错误（例如缺少必填的广告项参数）会在响应的
operation_errors对象下显示。
https://ads-api.x.com/12/batch/accounts/:account_id/line_items
参数
| 名称 | 说明 |
|---|---|
| operation_type 必填 | 针对每个项目所执行的操作类型。 类型：enum 可能的取值： Create、Delete、Update |
| params 必填 | 一个包含广告项对象全部参数的 JSON 对象。有关必填和可选的广告项参数列表，请参见此处。 |
POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items
PUT accounts/:account_id/line_items/:line_item_id
更新当前账户下的指定广告单元（line item）。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id
参数
| 名称 | 说明 |
|---|---|
| 帐户_id 必填项 | 杠杆账户的标识符。出现在该资源内’的路径，通常是所有 Advertiser API 请求的必填参数，但不包括GET 账户。指定的帐户必须与已认证的用户关联。 类型：字符串 示例： 18ce54d4x5t |
| 行_条目_id 必填项 | 对请求中所操作的行项目的引用。 类型：字符串 示例： 8v7jo |
| 广告主_域 可选项 | 此广告主的网站域名，不包含协议（protocol）。 注意：当广告条目…时必填’其投放位置被设置为 PUBLISHER_NETWORK。类型：字符串 示例： x.com |
| 广告主_用户_id 可选项 | 用于推广 PREROLL_VIEWS 广告的账号的 Twitter 用户标识符。只有特定客户端应用可以使用此参数。PREROLL_VIEWS广告。仅特定客户端应用可使用此参数。类型：字符串 示例： 312226591 |
| Android_应用_存储_标识符 可选项 | 用于推广的应用在 Google 应用商店中的标识符。 注意： APP_INSTALLS和APP_ENGAGEMENTS目标要求至少设置一个应用商店标识符——可以是android_app_store_identifier或ios_app_store_identifier。类型：字符串 示例： com.twitter.android |
| 目标受众_扩展字段 可选 | 通过定向触达与已目标用户相似的用户来扩大广告系列的覆盖范围。 类型：枚举 可能的值： BROAD，DEFINED，已展开 |
| 竞价_金额_本地_微型 可选 | 与该广告项目关联的出价金额。将使用与指定资金工具关联的货币。对于 USD，$5.50 表示为 5500000。 注意事项：在以下情况下必填 bid_strategy被设置为以下任意一种MAX或TARGET注意: 仅接受大于 0 的值。 类型：long 示例： 140000 |
| 出价_策略 可选项 | 出价机制。自动将根据每日预算和广告系列投放日期自动优化出价。MAX设定允许的最高出价，并且非仅在目标设置为触达或关注者.TARGET尝试将每日出价的平均值控制在指定值的±20%范围内bid_amount_local_micro且当目标设为覆盖范围或WEBSITE_CLICKS。注意: 如果设置为 自动，bid_amount_local_micro将忽略。注释：默认值由目标决定。 类型：枚举 可能的值： 自动,MAX，TARGET |
| 分类 （可选） | 该广告主的相关 IAB 分类。详见GET iab_categories。 注意事项：当该投放项…时必填’投放位置设置为 PUBLISHER_NETWORK。类型：字符串 示例： IAB3-1 |
| 时长_于_天数 可选项 | 在以下时间段内frequency_cap已实现。类型：int 可能的值： 1,7，30 |
| 实体_状态 （可选） | 该订单项的状态。 类型：枚举 可能的值： 活动，暂停 |
| 结束_时间 可选项 | 以 ISO 8601 表示的时间ISO 8601（日期与时间标准），表示该投放条目将停止投放。 类型：字符串 示例： 2017-10-05T00:00:00Z |
| 频率_上限 可选项 | 单个用户可接触到某条广告的最高投放次数。 注意：仅支持 覆盖，互动，VIDEO_VIEWS，和PREROLL_VIEWS目标。类型：int 示例： 5 |
| 目标 可选 | 与此投放项配合使用的优化设置。该APP_PURCHASES可用于APP_INSTALL。TheAPP_CLICKS和APP_INSTALLS可用于…的选项可用APP_INSTALL及APP_ENGAGEMENTS并且可能需要使用受支持的MACT 合作伙伴。注意：默认取决于目标。 类型：enum 可能的值： APP_CLICKS,APP_INSTALLS，APP_PURCHASES，互动度，FOLLOWERS，LINK_CLICKS，MAX_REACH，前贴片，PREROLL_STARTS，REACH_WITH_ENGAGEMENT,VIDEO_VIEW，VIEW_3S_100PCT,VIEW_6S，观看_15秒，WEBSITE_CONVERSIONS |
| iOS_应用_存储_标识符 可选 | 用于推广应用的 Apple App Store 标识符的数字部分。 注意: APP_INSTALLS和APP_ENGAGEMENTS目标需至少设置一个应用商店标识符——可以是android_app_store_identifier或ios_app_store_identifier.类型：字符串 示例： 333903271 |
| 名称 （可选） | 此广告项目的名称。 类型：字符串 示例： 示例 |
| 付款_作者： （可选） | 此行项目的计费单位。仅可为使用该单位的行项目修改此设置APP_INSTALLS目标。注意事项：默认 pay_by会根据广告系列目标和投放单元自动设置’的竞价单位。The APP_INSTALLS目标同时支持两者APP_CLICK和展示值。展示为默认值。The 链接点击目标同时支持LINK_CLICK及展示值。展示次数是默认值，但在将 bid_strategy 设置为 TARGET 时不支持TARGET适用于bid_strategy.The SITE_VISITS支持的目标曝光数值。类型：枚举 可能的值： APP_CLICK,展示,LINK_CLICK |
| 开始_时间 可选项 | 以 ISO 8601 格式表示的时间ISO 8601 标准，该项目将开始投放。 类型：string 示例： 2017-07-05T00:00:00Z |
| 合计_预算_金额_本地_微型 可选项 | 要分配给该行项目的总预算金额。将使用与指定资金工具关联的货币。对于美元 (USD)，$37.50 表示为 37500000。 类型：long 示例： 37500000 |
| 每日_预算_金额_本地_微型 （可选） | 要分配给广告系列的每日预算金额。将使用与指定资金工具关联的货币。对于 USD，$5.50 表示为 5500000。未提供时，广告系列将根据总预算并在广告投放期间平均消耗。仅当父级广告系列的 budget_optimization 设置为 LINE_ITEM 时可用budget_optimization设置为LINE_ITEM针对父级广告系列注意：应小于或等于 total_budget_amount_local_micro。类型：long 示例： 5500000 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000
示例响应
DELETE accounts/:account_id/line_items/:line_item_id
删除当前账户下指定的 line item。 注意：删除 line item 后不可恢复，之后再次尝试删除该资源将返回 HTTP 404。 注意：当 line item 被删除后，只有在请求中指定with_deleted=true 时，其子级 promoted_tweets 才会在 GET accounts/:account_id/promoted_tweets 和 GET accounts/:account_id/promoted_tweets/:promoted_tweet_id 端点中返回。这些 promoted_tweets 实际上并未被删除（响应中 "deleted": false）。我们不进行级联删除。
Resource URL
https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id
Parameters
| Name | Description |
|---|---|
| account_id required | 被使用的账户标识符。出现在资源路径中，通常是所有 Advertiser API 请求所需的参数（GET accounts 除外）。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| line_item_id required | 本次请求中要操作的 line item 的标识。 Type: string Example: 9f2ix |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix
Example Response
广告项精选分类
GET accounts/:account_id/line_item_curated_categories
检索与当前账户关联的部分或全部“line item 精选分类”的详情。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories
Parameters
| Name | Description |
|---|---|
| account_id required | 所使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| count optional | 指定每次请求尝试检索的记录数量。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string Example: 8x7v00oow |
| sort_by optional | 按受支持的属性进行升序或降序排序。更多信息参见 Sorting。 Type: string Example: created_at-asc |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | 在响应中包含 total_count 属性。Note: 此参数与 cursor 互斥。Note: 包含 total_count 的请求具有较低的速率限制，目前为每 15 分钟 200 次。Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories
Example Response
GET accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
检索与当前账户关联的特定广告条目精选分类的详细信息。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
Parameters
| Name | Description |
|---|---|
| account_id required | 被调用账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| line_item_curated_category_id required | 你在该请求中操作的广告条目精选分类的引用。 Type: string Example: 43853bhii885 |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav
Example Response
POST accounts/:account_id/line_item_curated_categories
将一个精选类别对象关联到指定的广告单元（line item）。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories
Parameters
| Name | Description |
|---|---|
account_id required | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
curated_category_id required | 你在本次请求中操作的精选类别实体的引用。 Type: string Example: 10miy |
line_item_id required | 你在本次请求中操作的广告单元（line item）的引用。 Type: string Example: 8v7jo |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o
Example Response
PUT accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
更新指定的 Line item 精选分类。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
Parameters
| Name | Description |
|---|---|
| account_id required | 被使用账户的标识符。出现在资源路径中，并且通常是除 GET accounts 以外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| line_item_curated_category_id required | 此请求中要操作的 Line item 精选分类的引用。 Type: string Example: 1bzq3 |
curated_category_id optional | 此请求中要操作的精选分类实体的引用。 Type: string Example: 10miy |
line_item_id optional | 此请求中要操作的 Line item 的引用。 Type: string Example: 8v7jo |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g
Example Response
DELETE accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
删除指定的广告项目精选类别。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。该参数出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| line_item_curated_category_id 必填 | 请求中要操作的广告项目精选类别的引用。 类型：string 示例： 1bzq3 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq
示例响应
订单项投放位置
GET line_items/placements
检索有效的placement 与 product_type 组合。
Resource URL
https://ads-api.x.com/12/line_items/placements
Parameters
| Name | Description |
|---|---|
| product_type optional | 将响应限定为指定产品类型对应的有效投放位置。 Type: enum Possible values: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS |
GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT
Example Response
媒体素材
GET accounts/:account_id/media_creatives
检索与当前账户关联的部分或全部媒体素材的详细信息。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/media_creatives
Parameters
| Name | Description |
|---|---|
| account_id required | 被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| campaign_id optional | 将响应限定为与指定广告系列关联的媒体素材。 Type: string Example: 8gdx6 |
| count optional | 指定每个请求尝试检索的记录数量。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string Example: 8x7v00oow |
| line_item_ids optional | 通过提供以逗号分隔的标识符列表，将响应限定为与指定投放项关联的媒体素材。最多可提供 200 个 ID。 Type: string Example: 8v7jo |
| media_creative_ids optional | 通过提供以逗号分隔的标识符列表，将响应限定为所需的媒体素材。最多可提供 200 个 ID。 Type: string Example: 1bzq3 |
| sort_by optional | 按支持的属性进行升序或降序排序。更多信息参见 Sorting。 Type: string Example: created_at-asc |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | 包含 total_count 响应属性。Note: 此参数与 cursor 互斥。Note: 包含 total_count 的请求将受到更低的速率限制，目前为每 15 分钟 200 次。Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3
Example Response
GET accounts/:account_id/media_creatives/:media_creative_id
检索与当前账户关联的特定媒体素材的详细信息。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id
参数
| Name | Description |
|---|---|
| account_id required | 目标账户的标识符。出现在资源路径中，通常是所有 Advertiser API 请求（除 GET accounts 之外）的必填参数。所指定账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| media_creative_id required | 本次请求中要操作的媒体素材的标识引用。 Type: string Example: 43853bhii885 |
| with_deleted optional | 是否在结果中包含已删除项。 Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3
示例响应
POST accounts/:account_id/media_creatives
将账户媒体对象与指定的广告组关联。 使用此端点在 Twitter Audience Platform 上推广流内广告（当账户媒体的creative_type 为 PREROLL）或图片广告（例如 BANNER 或 INTERSTITIAL）。
注意：如需向 Account Media 资源添加媒体资产，请使用 POST accounts/:account_id/media_library 端点。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/media_creatives
参数
| 名称 | 描述 |
|---|---|
account_id required | 被使用账户的标识符。出现在资源路径中，并且通常是所有 Advertiser API 请求（除 GET accounts 之外）的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
account_media_id required | 本次请求中所操作的账户媒体实体引用。 类型：string 示例： 10miy |
line_item_id required | 本次请求中所操作的广告组引用。 类型：string 示例： 8v7jo |
landing_url sometimes required | 引导用户访问的网站 URL。仅应与 TAP 图片（或“展示创意”）一起使用。用于 preroll 资产时将被忽略。要为 preroll 资产关联 URL，请使用 POST accounts/:account_id/preroll_call_to_actions 端点。 注意：当广告组的目标设置为 WEBSITE_CLICKS 时为必填。类型：string 示例： https://blog.x.com/ |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy
示例响应
DELETE accounts/:account_id/media_creatives/:media_creative_id
删除当前账户下的指定媒体创意。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与经过身份验证的用户关联。 类型：string 示例： 18ce54d4x5t |
| media_creative_id 必填 | 请求中要操作的媒体创意的引用。 类型：string 示例： 1bzq3 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3
示例响应
推广帐号
GET accounts/:account_id/promoted_accounts
检索当前账户下一个或多个投放项所关联的部分或全部推广账户的详细信息。 使用 GET users/lookup 获取响应中由user_id 标识的用户账户的数据。
如果指定的投放项均未配置包含推广账户，将返回 HTTP 400。
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promoted_accounts
Parameters
| Name | Description |
|---|---|
| account_id required | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| count optional | 指定每个请求尝试检索的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。详见 Pagination。 Type: string Example: 8x7v00oow |
| line_item_ids optional | 通过提供以逗号分隔的标识符列表，将响应限定为与指定投放项关联的推广账户。最多可提供 200 个 ID。 Type: string Example: 9bpb2 |
| promoted_account_ids optional | 通过提供以逗号分隔的标识符列表，将响应限定为指定的推广账户。最多可提供 200 个 ID。 Type: string Example: 19pl2 |
| sort_by optional | 按受支持的属性升序或降序排序。详见 Sorting。 Type: string Example: created_at-asc |
| with_deleted optional | 在结果中包含已删除的记录。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | 在响应中包含 total_count 属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求具有较低的速率限制，目前为每 15 分钟 200 次。Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2
Example Response
GET accounts/:account_id/promoted_accounts/:promoted_account_id
检索当前账户下某个广告项目所关联的特定账户引用。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id
参数
| Name | Description |
|---|---|
| account_id required | 被引用账户的标识符。该值出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与经认证的用户关联。 Type: string Example: 18ce54d4x5t |
| promoted_account_id required | 你在请求中操作的推广账户的引用。 Type: string Example: 19pl2 |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2
示例响应
POST accounts/:account_id/promoted_accounts
将账号（user_id）与指定的 line item 关联。
如果指定的 line item 未配置为可关联 Promoted Accounts，将返回 HTTP 400 INCOMPATIBLE_LINE_ITEM 错误。若指定用户不具备推广资格，将返回 HTTP 400，且不会推广任何用户。若所提供用户已在推广中，则会忽略该请求。
有关 Promoted Accounts 的更多信息，请参阅我们的广告系列管理页面。
注意：无法更新（PUT）promoted accounts 实体。
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promoted_accounts
Parameters
| Name | Description |
|---|---|
| account_id required | 目标账号的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账号必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| line_item_id required | 请求中正在操作的 line item 的引用。 Type: string Example: 9bpb2 |
| user_id required | 请求中正在操作的用户的引用。使用 GET users/lookup 通过 screen name 获取用户 ID。 Type: long Example: 756201191646691328 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328
Example Response
DELETE accounts/:account_id/promoted_accounts/:promoted_account_id
将某个账号与指定的广告项解除关联。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id
Parameters
| Name | Description |
|---|---|
| account_id required | 该投放账号的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定账号必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| promoted_account_id required | 与某个广告项相关联的 Promoted Account 实例的标识符。 Type: string Example: 19pl2 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2
Example Response
推广 Tweets
GET accounts/:account_id/promoted_tweets
检索与当前账户下广告分组（line items）关联的 Tweet 引用。 使用 GET accounts/:account_id/tweets 端点获取 Tweet 对象。对每个 promoted_tweets 对象使用其tweet_id 值。
注意：当父级广告分组（line items）被删除时，仅当请求中指定 with_deleted=true 时才会返回 promoted_tweets。不过这些 promoted_tweets 实际上并未被删除（响应中为 "deleted": false）。
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promoted_tweets
Parameters
| Name | Description |
|---|---|
| account_id required | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| count optional | 指定每个请求尝试检索的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。详见 Pagination。 Type: string Example: 8x7v00oow |
| line_item_ids optional | 通过指定以逗号分隔的标识符列表，将响应限定为与特定广告分组（line items）关联的 Tweets。最多可提供 200 个 ID。 Type: string Example: 96uzp |
| promoted_tweet_ids optional | 通过指定以逗号分隔的标识符列表，将响应限定为所需的推广 Tweets。最多可提供 200 个 ID。 Type: string Example: 1efwlo |
| sort_by optional | 按支持的属性进行升序或降序排序。详见 Sorting。 Type: string Example: created_at-asc |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | 在响应中包含 total_count 属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求将适用更低的速率限制，目前为每 15 分钟 200 次。Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo
Example Response
GET accounts/:account_id/promoted_tweets/:promoted_tweet_id
检索当前账户下某个投放单元所关联的特定 Tweet 引用。 注意：当父级投放单元被删除时，只有在请求中指定with_deleted=true 时才会返回 promoted_tweets。但这些 promoted_tweets 实际并未被删除（响应中为 "deleted": false"）。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| promoted_tweet_id 必填 | 你在请求中操作的被推广 Tweet 的引用。 类型：string 示例： 1efwlo |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值： false 可能的取值： true、false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo
示例响应
POST accounts/:account_id/promoted_tweets
将一个或多个 Tweet 关联到指定的广告项（line item）。并非所有 Tweet 都适合推广，具体取决于广告系列目标。请参阅基于目标的广告系列了解更多信息。 当使用PROMOTED_ACCOUNT 产品类型时，将 Tweet 关联到 line_item 除了标准的 PROMOTED_ACCOUNT 投放位置外，还会在移动端时间线中添加投放位置。
注意：无法更新（PUT）已推广的 Tweet 实体。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/promoted_tweets
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| line_item_id 必填 | 本次请求所操作的广告项（line item）的引用。 类型：string 示例： 8v7jo |
| tweet_ids 必填 | 以逗号分隔的标识符列表，对应特定的 Tweet。最多可提供 50 个 ID。 类型：long 示例： 822333526255120384 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384
示例响应
DELETE accounts/:account_id/promoted_tweets/:promoted_tweet_id
将某条 Tweet 与指定的广告单元（line item）解除关联。 注意：被删除的 promoted_tweets 实体将在 ads.x.com 界面中显示为“已暂停”。同样，从界面执行“暂停”操作也会将该 Tweet 与其广告单元解除关联。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id
Parameters
| Name | Description |
|---|---|
| account_id required | 使用中的账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| promoted_tweet_id required | 指向与某个广告单元关联的 Promoted Tweet 实例的标识符。该值来自 GET accounts/:account_id/promoted_tweets 响应项中的 id 字段，而不是该 Tweet 的 tweet_id。在资源路径中提供。Type: string Example: 1gp8a5 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5
Example Response
可投放推广的用户
GET accounts/:account_id/promotable_users
检索与当前账户关联的部分或全部可推广用户的详细信息。 可推广用户类型为FULL 或 RETWEETS_ONLY，用于控制该账户可推广的内容类型。广告主在推广其他用户的内容前必须获得许可，并联系 X，将该用户以 RETWEETS_ONLY 可推广用户的身份添加到你的账户中。
在权限配置正确的前提下，你可以向推广产品相关的端点发起请求，直接引用你想推广的 Tweet 的 Tweet ID。你可以使用 POST accounts/:account_id/promoted-tweets 端点推广已发布的 Tweets，或使用 POST accounts/:account_id/scheduled-promoted-tweets 端点推广其他 X Ads 账户的已排期 Tweets。
你无需转发目标 Tweet。使用此方式推广时，返回的 tweet_id 将不同于你提供的 Tweet ID。系统会在后台将该 Tweet 以“nullcasted Tweet”的形式转发后再进行推广。返回的 tweet_id 对应的是这个新的 Tweet。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/promotable_users
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 以外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| count 可选 | 指定每个请求尝试检索的记录数量。 类型：int 默认值： 200 最小值、最大值： 1、1000 |
| cursor 可选 | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 类型：string 示例： 8x7v00oow |
| promotable_user_ids 可选 | 通过指定以逗号分隔的标识符列表，将响应范围限定为所需的可推广用户。最多可提供 200 个 ID。 类型：string 示例： l310s |
| sort_by 可选 | 按受支持的属性进行升序或降序排序。更多信息参见 Sorting。 类型：string 示例： created_at-asc |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值： false 可能的取值： true、false |
| with_total_count 可选 | 在响应中包含 total_count 属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求将具有更低的速率限制，目前为每 15 分钟 200 次。类型：boolean 默认值： false 可能的取值： true、false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s
示例响应
GET accounts/:account_id/promotable_users/:promotable_user_id
检索与当前账户关联的特定可推广用户。 可推广用户类型为FULL 或 RETWEETS_ONLY。这将决定该账户允许推广的内容类型。
广告主必须获得推广他人内容的权限。在权限设置正确的情况下，您可以向推广产品相关的端点发起请求，直接引用希望推广的 Tweet 的 Tweet ID。
无需转发目标 Tweet。使用此方式推广 Tweet 时，返回的 tweet_id 将不同于您提供的 Tweet ID。在后台，该 Tweet 会作为“nullcast”Tweet 被转发，然后进行推广。返回的 tweet_id 对应这一条新的 Tweet。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/promotable_users/:promotable_user_id
参数
| 名称 | 描述 |
|---|---|
| account_id required | 目标账户的标识符。出现在资源路径中，并且通常是所有 Advertiser API 请求（不包括 GET accounts）的必需参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| promotable_user_id optional | 您在请求中要操作的可推广用户的引用。 Type: string Example: l310s |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s
示例响应
发布方
https://ads-api.x.com/12/publishers
参数
无请求参数
示例请求
GET https://ads-api.x.com/12/publishers
示例响应
建议
GET accounts/:account_id/recommendations
状态：封闭 Beta 检索与此广告账户关联的广告系列推荐。目前每个资金工具最多 1 条推荐。 资源 URLhttps://ads-api.x.com/5/accounts/:account_id/recommendations
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用账户的标识符。它出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已验证用户关联。 类型：string 示例： 18ce54d4x5t |
GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations
示例响应
GET accounts/:account_id/recommendations/:recommendation_id
状态：封闭测试 检索与此广告账户关联的特定广告系列推荐。 广告系列推荐包含针对广告系列结构的一整套变更建议，呈现为对象树。响应树旨在与 Batch API 端点配合使用，但也可按需映射到单个更新端点（POST 为创建、PUT 为更新、DELETE 为删除）。 资源 URLhttps://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| recommendation_id 必填 | 你在该请求中要操作的推荐 ID。 类型：string 示例： 62ce8zza1q0w |
GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w
示例响应
计划投放的推广 Tweet
GET accounts/:account_id/scheduled_promoted_tweets
检索与当前账户关联的部分或全部已排期的推广 Tweet 的详细信息。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets
参数
| Name | Description |
|---|---|
| account_id required | 被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| count optional | 指定每个请求尝试检索的记录数量。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。参见 Pagination 了解更多信息。 Type: string Example: 8x7v00oow |
| line_item_ids optional | 通过提供以逗号分隔的标识符列表，将响应限定为与特定 line item 关联的已排期 Tweet。最多可提供 200 个 ID。 Type: string Example: 8xdpe |
| scheduled_promoted_tweet_ids optional | 通过提供以逗号分隔的标识符列表，将响应限定为所需的已排期推广 Tweet。最多可提供 200 个 ID。 Type: string Example: 1xboq |
| sort_by optional | 按受支持的属性进行升序或降序排序。参见 Sorting 了解更多信息。 Type: string Example: created_at-asc |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | 在响应中包含 total_count 属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求将有较低的速率限制，目前为每 15 分钟 200 次。Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq
示例响应
GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id
获取与当前账户关联的特定已排期的推广 Tweet。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 所使用账户的标识符。出现在资源路径中，且通常为除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与经过认证的用户关联。 类型：string 示例： 18ce54d4x5t |
| scheduled_promoted_tweet_id 必填 | 你在请求中操作的已排期推广 Tweet 的引用。 类型：string 示例： 1xboq |
| with_deleted 可选 | 在请求中包含已删除的结果。 类型：boolean 默认值： false 可能的取值： true、false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq
示例响应
POST accounts/:account_id/scheduled_promoted_tweets
将计划的 Tweet 与指定的投放单（line item）关联。 Note: 无法更新（PUT）计划的推广 Tweet 实体。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets
Parameters
| Name | Description |
|---|---|
| account_id required | 所使用账号的标识符。出现在资源路径中，通常是所有 Advertiser API 请求（不包括 GET accounts）的必需参数。指定的账号必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| line_item_id required | 请求中所操作的投放单（line item）的引用。 Type: string Example: 8xdpe |
| scheduled_tweet_id required | 请求中所操作的计划 Tweet 的引用。 Type: long Example: 870358555227860992 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992
Example Response
DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id
将已排期的 Tweet 与指定的投放单元（line item）解除关联。 注意：只能在该 Tweet 的scheduled_at 排期时间之前删除 scheduled_promoted_tweets。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
参数
| 名称 | 说明 |
|---|---|
| account_id 必填 | 目标账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| scheduled_promoted_tweet_id 必填 | 本次请求中要操作的已排期推广 Tweet 的引用。即来自 GET accounts/:account_id/scheduled_promoted_tweets 响应对象的 id 属性。类型：string 示例： 1xtfl |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl
示例响应
定向标准
GET accounts/:account_id/targeting_criteria
检索当前账户下各 Line Item 关联的部分或全部定向条件详情。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/targeting_criteria
Parameters
| Name | Description |
|---|---|
| account_id required | 被使用的账户标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| line_item_ids required | 通过指定以逗号分隔的标识符列表，仅返回所指定 Line Item 下的定向条件。最多可提供 200 个 ID。 Type: string Example: 8u94t |
| count optional | 指定每个请求尝试检索的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string Example: 8x7v00oow |
| lang optional | 一个 ISO-639-1 语言代码。传入时，如对象存在本地化名称，将在响应中返回额外的 localized_name 属性。Type: string Example: fr |
| sort_by optional | 按受支持的属性进行升序或降序排序。更多信息参见 Sorting。 Type: string Example: created_at-asc |
| targeting_criterion_ids optional | 通过指定以逗号分隔的标识符列表，仅返回所需的定向条件。最多可提供 200 个 ID。 Type: string Example: dpl3a6 |
| with_deleted optional | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | 在响应中包含 total_count 属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求将具有较低的速率限制，目前为每 15 分钟 200 次。Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t
Example Response
GET accounts/:account_id/targeting_criteria/:targeting_criterion_id
获取与当前账户关联的特定定向条件。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id
参数
| Name | Description |
|---|---|
| account_id required | 被使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| targeting_criterion_id required | 请求中要操作的定向条件的标识引用。 类型：string 示例： eijd4y |
| lang optional | ISO-639-1 语言代码。传入该参数时，对于具备本地化名称的对象，响应中会额外返回 localized_name 属性。类型：string 示例： fr |
| with_deleted optional | 在请求中包含已删除的结果。 类型：boolean 默认值： false 可选值： true、false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y
示例响应
POST accounts/:account_id/targeting_criteria
请参阅 Targeting Options 页面以查找特定定向类型的targeting_value。我们建议每周刷新所有 data，确保你使用的是最新的一组定向类型取值。我们会不时更改取值和可用的定向条件；尽管其中大多数不常变动，但也有一些会变动。无法保证这些取值不会变化。
将 BROAD_KEYWORD、EXACT_KEYWORD、PHRASE_KEYWORD 或 UNORDERED_KEYWORD 定向类型与 targeting_value 中指定的关键词配合使用。通过将请求参数 operator_type 设置为 NE 来排除关键词。请参阅 targeting keyword types 以了解每种类型的详细说明。
注意：每个 line item 只能定向一个年龄分段。
注意：要定向到 Custom Audience，该受众必须是可定向的。即 targetable 必须等于 true。
注意：使用 TV_SHOW 定向类型时，在设置 TV_SHOW 定向之前，line item 上必须至少有一个 LOCATION 定向条件，且所有 LOCATION 的区域设置必须与所定向的 TV_SHOW 相同。
Resource URL
https://ads-api.x.com/12/accounts/:account_id/targeting_criteria
Parameters
| Name | Description |
|---|---|
| account_id required | 所使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| line_item_id required | 你在请求中操作的 line item 的引用。 Type: string Example: 69ob |
| operator_type required | 指定定向条件应具有的关系。例如，要排除关键词，使用 operator_type=NE。Type: enum Possible values: EQ, NE, GTE, LT |
| targeting_type required | 将应用于此 line item 的定向类型。 可能的非关键词类型包括： AGE、DEVICE、EVENT、CAMPAIGN_ENGAGEMENT、CAMPAIGN_ENGAGEMENT_LOOKALIKE、CONVERSATION、ENGAGEMENT_TYPE、FOLLOWERS_OF_USER、GENDER、INTEREST、LANGUAGE、LIVE_TV_EVENT、LOCATION、NETWORK_ACTIVATION_DURATION、NETWORK_OPERATOR、PLATFORM、PLATFORM_VERSION、SIMILAR_TO_FOLLOWERS_OF_USER、TV_SHOW、USER_ENGAGEMENT、USER_ENGAGEMENT_LOOKALIKE、WIFI_ONLY注意：每个 line item 只能定向一个 AGE 分段。可能的关键词类型包括： BROAD_KEYWORD、EXACT_KEYWORD、PHRASE_KEYWORD、UNORDERED_KEYWORD可能的自定义受众类型包括： CUSTOM_AUDIENCE、CUSTOM_AUDIENCE_EXPANDED可能的已安装应用商店分类类型： APP_STORE_CATEGORY、APP_STORE_CATEGORY_LOOKALIKE可能的 Twitter Audience Platform (TAP) 应用排除： APP_LIST（仅可与 operator_type=NE 一起使用） |
| targeting_value required | 根据所选的 targeting_type，指定此定向将应用于哪个用户、哪个兴趣、哪个位置、哪个事件、哪个平台、哪个平台版本、哪个设备、哪个关键词或短语、哪个性别、哪个自定义受众、哪个应用商店分类，或排除哪个应用列表。 Type: string Example: 174958347 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology
示例响应
POST batch/accounts/:account_id/targeting_criteria
允许通过单个请求批量创建新的 Targeting Criteria（定向条件）。 批量请求- 当前最大批量大小为 500。
- 所有参数均在请求正文中发送，并且必须使用
application/json的Content-Type。 - 批量请求作为一个整体成败一致，且无论成功还是失败，所有 API 响应都会保留初始请求中各项的顺序。
- 请求级错误（如超过最大批量大小）会在响应的
errors对象下显示。 - 项目级错误（如缺少必需的 Targeting Criteria 参数）会在响应的
operation_errors对象下显示。
https://ads-api.x.com/12/batch/accounts/:account_id/targeting_criteria
参数
| Name | Description |
|---|---|
| operation_type required | 针对每个项目执行的操作类型。 Type: enum Possible values: Create, Delete |
| params required | 一个包含所有定向条件对象参数的 JSON 对象。有关必填和可选的定向条件参数，请参见此处。 此外，此端点支持一个与某些 targeting_type 值配合使用的 operator_type 参数。该参数的可选值为：EQ（等于）、GTE（大于等于）、LT（小于）和 NE（不等于）。 |
POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/targeting_criteria
DELETE accounts/:account_id/targeting_criteria/:targeting_criterion_id
删除当前账户下指定的定向条件。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必填 | 被使用账户的标识符。该值出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| targeting_criterion_id 必填 | 请求中所操作的定向条件的引用。 类型：string 示例： dpl3a6 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6
示例响应
定向选项
GET targeting_criteria/app_store_categories
查找可用于推广产品的应用商店类别定向条件。应用商店类别仅适用于 iOS App Store 和 Google Play 商店。 “已安装应用类别”定向允许根据用户已安装或表达兴趣的应用类别进行投放。 Resource URLhttps://ads-api.x.com/12/targeting_criteria/app_store_categories
Parameters
| Name | Description |
|---|---|
| q optional | 用于限定定向条件范围的可选查询。省略此参数以检索全部结果。 Type: string Example: music |
| os_type optional | 按特定应用商店限定结果范围。 Type: enum Possible values: ANDROID, IOS |
GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS
Example Response
GET targeting_criteria/conversations
探索可用于推广产品的基于会话的定向条件。 Resource URLhttps://ads-api.x.com/12/targeting_criteria/conversations
Parameters
| Name | Description |
|---|---|
| conversation_type optional | 可选查询，用于限定为某一会话类型。 Type: enum 可选值： ACTORS、ATHLETES、BOOK_GENRES、BOOKS、BRAND_CATEGORIES、BRANDS、CELEBRITIES、COACHES、DIGITAL_CREATORS、ENTERTAINMENT_BRANDS、ENTERTAINMENT_PERSONALITIES、FICTIONAL_CHARACTERS、JOURNALISTS、LIFESTYLES、MOVIE_GENRES、MOVIES、MUSIC_GENRES、MUSICIANS、NEWS_STORIES、NEWS、PERSONS、PLACES、PODCASTS、POLITICAL_AFFILIATIONS、POLITICIANS、PRODUCTS、RADIO_STATIONS、SPORTS_LEAGUES、SPORTS_PERSONALITIES、SPORTS_TEAMS、SPORTS、TRENDS、TV_SHOWS、VIDEO_GAME_PLATFORMS、VIDEO_GAME_PUBLISHERS、VIDEO_GAMES |
| count optional | 指定每个请求要检索的记录数。 Type: int Default: 200 Min, Max: 1、1000 |
| cursor optional | 指定用于获取下一页结果的游标。有关更多信息，请参见 Pagination。 Type: string Example: 8x7v00oow |
GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2
Example Response
GET targeting_criteria/devices
了解可用于推广产品的设备维度定向条件。设备定向适用于推广 Tweet。 Resource URLhttps://ads-api.x.com/12/targeting_criteria/devices
Parameters
| Name | Description |
|---|---|
| count optional | 指定每个请求尝试获取的记录数量。 Type: int Default: 200 Min, Max: 1, 1000 |
| q optional | 用于限定定向条件范围的可选查询。省略此参数可检索全部。 Type: string Example: apple |
GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone
Example Response
GET targeting_criteria/events
查找可用于 Promoted Products 的基于事件的定向条件。每个 line item 只能定向一个事件。 注意：事件常常跨越时区，从跨时区角度考虑事件时间会带来复杂性。为简化处理，此端点上的所有事件start_time 和 end_time 值均以 UTC±00:00 表示，而不考虑事件的本地与时区。查询与使用事件的 start_time 和 end_time 值时应注意这一设计。例如，美国的 Independence Day 在 UTC±00:00 下表示为 start_time=2017-07-04T00:00:00Z 和 end_time=2017-07-05T00:00:00Z，从而避免了该节日在美国境内跨多个时区所带来的问题。
Resource URL
https://ads-api.x.com/12/targeting_criteria/events
Parameters
| Name | Description |
|---|---|
| event_types required | 可选查询，用于限定到特定事件类型。 Type: enum Possible values: CONFERENCE, HOLIDAY, MUSIC_AND_ENTERTAINMENT, OTHER, POLITICS, RECURRING, SPORTS |
| count optional | 指定每个请求尝试检索的记录数量。 Type: int Default: 200 Min, Max: 1, 1000 |
| country_codes optional | 可选查询，使用两字母 ISO 国家代码将定向条件搜索限定到特定国家。若未指定此参数，则返回所有事件。 Type: string |
| cursor optional | 指定用于获取下一页结果的游标。参见 Pagination 了解更多信息。 Type: string Example: 8x7v00oow |
| end_time optional | 以 ISO 8601 表示的 campaign 结束时间。 Type: string Example: 2017-10-05T00:00:00Z |
| start_time optional | 以 ISO 8601 表示的 line item 开始投放时间。 注意：默认为当前时间。 Type: string Example: 2017-07-05T00:00:00Z |
GET https://ads-api.x.com/12/targeting_criteria/events?count=1
Example Response
GET targeting_criteria/interests
查找可用于推广产品的兴趣定向条件。兴趣列表变动不频繁，但建议至少每周刷新一次。 Resource URLhttps://ads-api.x.com/12/targeting_criteria/interests
Parameters
| Name | Description |
|---|---|
| count optional | 指定每次请求尝试检索的记录数量。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。有关更多信息，请参见 Pagination。 Type: string Example: 8x7v00oow |
| q optional | 可选查询，用于限定定向条件范围。若要检索全部，请省略此参数。 Type: string Example: books |
GET https://ads-api.x.com/12/targeting_criteria/interests?q=books
Example Response
GET targeting_criteria/languages
发现可用于投放定向的语言。 Resource URLhttps://ads-api.x.com/12/targeting_criteria/languages
Parameters
| Name | Description |
|---|---|
| count optional | 指定每个请求尝试检索的记录数量。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 指定用于获取下一页结果的游标。参见 Pagination 了解更多信息。 Type: string Example: 8x7v00oow |
| q optional | 可选查询参数，用于限定定向条件。不传此参数则检索全部。 Type: string Example: english |
GET https://ads-api.x.com/12/targeting_criteria/languages?q=english
Example Response
GET targeting_criteria/locations
发现可用于 Promoted Products 的基于位置的定向条件。地理定向适用于国家级、州/地区级、城市级和邮政编码级的 Promoted Accounts 和 Promoted Tweets。若希望在邮政编码级别获取分析数据，必须使用邮政编码定向。 注意：要检索可定向的特定城市（例如 San Francisco 或 New York），请在请求参数location_type 中使用枚举 CITIES。
要定向 Designated Market Areas（DMA），请使用枚举 METROS。
Resource URL
https://ads-api.x.com/12/targeting_criteria/locations
Parameters
| Name | Description |
|---|---|
| count optional | 指定每个请求尝试检索的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| country_code optional | 可选查询，使用 2 位 ISO 国家代码将定向条件搜索限定在特定国家。省略此参数可检索所有国家的结果。 Type: string Example: JP |
| cursor optional | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string Example: 8x7v00oow |
| location_type optional | 按特定位置类型限定结果。细于 COUNTRIES 的定向在所有地区可能不可用。Type: enum Possible values: COUNTRIES, REGIONS, METROS, CITIES, POSTAL_CODES |
| q optional | 可选查询，用于限定定向条件搜索。省略此参数将检索所有结果。 Type: string Example: New York |
GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles
Example Response
GET targeting_criteria/network_operators
查找可用于推广产品的基于网络运营商的定向条件。 此端点可在多个国家/地区查询可用于定向的运营商，例如 AT&T、Verizon、Sprint、T-Mobile 等。 Resource URLhttps://ads-api.x.com/12/targeting_criteria/network_operators
Parameters
| Name | Description |
|---|---|
| count optional | 指定每个请求尝试检索的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| country_code optional | 可选查询参数，使用两位 ISO 国家代码将定向条件搜索范围限定到特定国家/地区。若未指定该参数，则仅返回美国的合作伙伴受众。 Type: string Default: US |
| cursor optional | 指定用于获取下一页结果的游标。参见 Pagination 了解更多信息。 Type: string Example: 8x7v00oow |
| q optional | 可选查询参数，用于限定定向条件搜索范围。省略该参数以检索所有结果。 Type: string Examples: Airpeak |
GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US
Example Response
GET targeting_criteria/platform_versions
查找适用于推广产品的可用移动操作系统版本定位条件。平台版本定位适用于推广账号和推广Tweet。这使您可以将定位精确到移动操作系统的次级版本，例如 Android 8.0 或 iOS 10.0。 资源 URLhttps://ads-api.x.com/12/targeting_criteria/platform_versions
参数
| 名称 | 描述 |
|---|---|
| q 可选 | 用于限定定位条件搜索范围的可选查询。省略此参数以检索所有结果。 类型：string 示例： jelly bean |
GET https://ads-api.x.com/12/targeting_criteria/platform_versions
示例响应
GET targeting_criteria/platforms
查找适用于 Promoted Products 的可用平台定向条件。 Resource URLhttps://ads-api.x.com/12/targeting_criteria/platforms
Parameters
| Name | Description |
|---|---|
| count optional | 指定每个请求尝试检索的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| q optional | 可选的查询，用于限定定向条件搜索范围。省略此参数以检索所有结果。 Type: string Examples: ios, blackberry |
| lang optional | 使用 ISO-639-1 语言代码。传入后，响应中会返回一个额外的 localized_name 属性。 Type: int, string Example: fr |
GET https://ads-api.x.com/12/targeting_criteria/platforms
Example Response
GET targeting_criteria/tv_markets
查找可用于投放 TV 节目的可用 TV 市场。按语言区域返回市场，可用于查询 GET targeting_criteria/tv_shows 端点。 Resource URLhttps://ads-api.x.com/12/targeting_criteria/tv_markets
Parameters
无
Example Request
GET https://ads-api.x.com/12/targeting_criteria/tv_markets
Example Response
GET targeting_criteria/tv_shows
查看可用于推广产品的基于电视节目的定向条件。电视节目定向在部分市场的推广 Tweets 中可用。可用市场请参见 GET targeting_criteria/tv_markets 端点。 注意：任何受众如果少于 1,000 名用户，其estimated_users 值将显示为 1000。
注意：不再支持电视频道和类型（genre）定向选项。
Resource URL
https://ads-api.x.com/12/targeting_criteria/tv_shows
Parameters
| Name | Description |
|---|---|
| locale required | 必填参数，用于指定要查询可用电视节目的 tv_market_locale。将基于从 GET targeting_criteria/tv_markets 返回的 locale 查询电视市场。Type: string Example: en-US |
| count optional | 指定每次请求尝试检索的记录数。 Type: int Default: 50 Min, Max: 1, 50 |
| cursor optional | 指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string Example: 8x7v00oow |
| q optional | 可选查询，用于限定定向条件的搜索范围。省略此参数以检索所有结果。 Type: string Examples: ios, blackberry |
GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1
Example Response
目标受众建议
GET accounts/:account_id/targeting_suggestions
获取最多 50 条关键词或用户定向建议，以补充你的初始选择。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/targeting_suggestions
Parameters
| Name | Description |
|---|---|
| account_id required | 被使用账户的标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与进行身份验证的用户关联。 Type: string Example: 18ce54d4x5t |
| suggestion_type required | 指定要返回的建议类型。 Type: enum Possible values: KEYWORD, USER_ID |
| targeting_values required | 以逗号分隔的一组关键词或用户 ID，用于作为建议的种子输入。 Note: 这两种类型的建议不能混用。 Example: 756201191646691328 |
| count optional | 指定每个独立请求尝试检索的记录数。 Type: int Default: 30 Min, Max: 1, 50 |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"
Example Response
税务设置
GET accounts/:account_id/tax_settings
获取与当前账户关联的税务设置详情。 Resource URLhttps://ads-api.x.com/12/accounts/:account_id/tax_settings
Parameters
| Name | Description |
|---|---|
| account_id required | 目标账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所需的必填参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings
Example Response
PUT accounts/:account_id/tax_settings
更新当前账户的税务设置。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/tax_settings
参数
| 名称 | 说明 | |
|---|---|---|
| 帐户_id 必填项 | 杠杆账户的标识符。出现在该资源中’的路径中，且通常是所有广告主 API 请求的必需参数，除外GET 账户。指定的账号必须与已通过身份验证的用户关联。 类型：字符串 示例： 18ce54d4x5t | |
| 地址_城市 可选项 | 账户所有者所在城市’的地址。 类型：字符串 示例： 旧金山 | |
| 地址_国家/地区 可选 | 账户所有者的双字母国家/地区代码’的地址。 类型：字符串 示例： 美国 | |
| 地址_邮箱 可选 | 与帐号所有者关联的电子邮件地址’的地址。 类型：字符串 示例： api@mctestface.com | |
| 地址_第一_名称 （可选） | 账户所有者的名’的地址。 类型：字符串 示例： API | |
| 地址_最后_名称 可选项 | 账户所有者的姓’地址。 类型：string 示例： McTestface | |
| 地址_名称 （可选） | 账户拥有者的公司名称’的地址。 类型：字符串 示例： ABC 公司 | |
| 地址_邮寄_代码 可选项 | 账户所有者的邮政编码’的地址。 类型：字符串 示例： 94102 | |
| 地址_区域 （可选） | 账户所有者的地区’的地址。 类型：字符串 示例： 加利福尼亚州 | |
| 地址_街道1 可选 | 账户所有者的街道地址行’的地址。 类型：字符串 示例： 马奇街21号 | |
| 地址_street2 可选 | 账户所有者的街道地址第二行’的地址。 类型：string 示例： Suite 99 | |
| 账单_bill_to optional | 计费实体。 类型：枚举 可能的值： ADVERTISER, AGENCY可选 | 被计费的实体。 类型：枚举 可能的值： 广告主计费实体。类型：枚举 可能值： ADVERTISER, AGENCY``代理机构 |
| 业务_关系 可选 | 账户是由广告主还是代理机构拥有。 类型：枚举 可能的值： 代理机构，SELF | |
| 客户端client_address_city 可选地址_城市 可选 | 广告主的城市’广告主的地址。 当广告账户由代理机构拥有时，设置此项。 类型：string 示例： 多伦多 | |
| 客户端client_address_country 可选地址_国家 可选 | 广告主的两位字母国家代码’的地址。 如果广告账户由代理机构拥有，请设置此项。 类型：string 示例： CA | |
| 客户端_地址_电子邮件 可选 | 与广告主关联的电子邮件’与广告主地址关联的电子邮件地址。 当广告账户由代理机构拥有时，请设置此项。 类型：string 示例： ads@brand.com当广告账户属于代理机构时，设置此项。 类型：string 示例： ads@brand.com | |
| 客户端client_address_first_name 可选地址_第一_名称 可选 | 广告主的名’的地址。 当广告账户由代理机构拥有时设置此项。 类型：string 示例： 品牌 | |
| 客户端_地址client_address_last_name 可选姓client_address_last_name 可选名称 可选 | 广告主的姓氏’的地址。 当广告账户由代理机构拥有时，请设置此项。 类型: string 示例： 广告主 | |
| 客户端_地址广告主地址的公司名称。 当广告账户由代理机构持有时，请设置此字段。 类型：string 示例： Brand, Inc.名称可选 | 广告主的公司名称’的地址。 当广告账户由代理机构拥有时，设置此项。 类型：字符串 广告主地址的公司名称。<br /><br />当广告账户由代理机构拥有时，请设置此项。<br /><br />类型：字符串<br /><br />示例： Brand, Inc.``Brand, Inc. | |
| 客户端_地址_邮政_代码 可选 | 广告主的邮政编码’广告主的地址。 当广告账户由代理机构拥有时，设置此项。 类型：字符串 示例： M5H 2N2 | |
| 客户端_地址_地区 可选 | 广告主的地区’的地址。 如果广告账户由代理机构拥有，请设置此项。 类型：string 示例： Ontario | |
| 客户端_地址_街道地址1 可选 | 广告主的街道地址行’的地址。 当广告账户由代理机构拥有时，设置此项。 类型：字符串 示例： 280 Queen St W | |
| 客户端_地址_街道地址 2 可选 | 广告主的街道地址第2行’的地址。 当广告账户由代理商拥有时设置此项。 类型：字符串 示例： 第 6 个 | |
| 发票_司法管辖权 可选 | 发票适用司法管辖区。 类型：枚举 可能的值： LOI_SAPIN，无，未设置 | |
| 税_分类 可选项 | 税务应归类为个人还是企业？ 类型：枚举 可能的值： BUSINESS_NO_VAT，BUSINESS_WITH_VAT，个人 | |
| 税务_豁免_id 可选 | 增值税免税id。 Type: 字符串 示例： 12345 | |
| 税_id 可选（可不填） | 增值税注册id。 类型：字符串 可能的值： 67890 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.
示例响应
GET accounts/:account_id/tracking_tags
获取与当前账户关联的某些或所有跟踪标签的详细信息。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags
参数
| Name | Description |
|---|---|
| account_id 必需 | 使用的账户的标识符。出现在资源的路径中，并且通常是除 GET accounts 外的所有广告主 API 请求的必需参数。指定的账户必须与已认证用户关联。 Type: string Example: 18ce54d4x5t |
| count 可选 | 指定每个请求尝试返回的记录数。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor 可选 | 指定一个游标以获取下一页结果。有关详细信息，请参阅 分页。 Type: string Example: 8x7v00oow |
| line_item_ids 可选 | 通过指定逗号分隔的标识符列表，将响应限定到与特定行项目关联的跟踪标签。最多可提供 200 个 ID。 Type: string Example: 96uzp |
| sort_by 可选 | 按支持的属性以升序或降序排序。有关详细信息，请参阅 排序。 Type: string Example: created_at-asc |
| tracking_tag_ids 可选 | 通过指定逗号分隔的标识符列表，将响应限定到所需的跟踪标签。最多可提供 200 个 ID。 Type: string Example: 3m82 |
| with_deleted 可选 | 在请求中包含已删除的结果。 Type: boolean Default: false Possible values: true, false |
| with_total_count 可选 | 包含 total_count 响应属性。注意：此参数与 cursor 互斥。注意：包含 total_count 的请求将具有较低的速率限制，目前设置为每 15 分钟 200 次。Type: boolean Default: false Possible values: true, false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82
示例响应
GET accounts/:account_id/tracking_tags/:tracking_tag_id
检索当前账户关联的特定跟踪标签。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id
参数
| Name | Description |
|---|---|
| account_id required | 所使用账户的标识符。出现在资源的路径中，通常是所有广告主 API 请求的必需参数（GET accounts 除外）。指定的账户必须与已认证用户关联。 类型：string 示例： 18ce54d4x5t |
| tracking_tag_id required | 本次请求中操作的跟踪标签的引用。 类型：string 示例： 555j |
| with_deleted optional | 将已删除的结果包含在您的请求中。 类型：boolean 默认值： false 可能值： true、false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j
示例响应
POST accounts/:account_id/tracking_tags
将跟踪标签与指定的行项目关联。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags
参数
| Name | Description |
|---|---|
| account_id 必需 | 所用账户的标识符。出现在资源的路径中，并且通常是所有广告主 API 请求的必需参数（GET accounts 除外）。指定的账户必须与经过身份验证的用户关联。 类型：string 示例： 18ce54d4x5t |
| line_item_id 必需 | 请求中要操作的行项目的 ID。 类型：string 示例： 8v7jo |
| tracking_tag_type 必需 | 跟踪标签类型。 类型：enum 可能值： IMPRESSION_TAG、CLICK_TRACKER |
| tracking_tag_url 必需 | 由跟踪合作伙伴提供的跟踪标签 URL。 类型：string 示例： https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?line_item_id=fdwcl&tracking_tag_type=IMPRESSION_TAG&tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309
示例响应
PUT accounts/:account_id/tracking_tags/:tracking_tag_id
将跟踪标签与指定的行项目关联。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必需 | 使用的账户的标识符。它位于资源的路径中，通常是除 GET accounts 外的所有广告主 API 请求的必需参数。指定的账户必须与已认证用户关联。 类型：字符串 示例： 18ce54d4x5t |
| tracking_tag_url 必需 | 由跟踪合作伙伴提供的跟踪标签 URL。 类型：字符串 示例： https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/3m82?tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309
示例响应
DELETE accounts/:account_id/tracking_tags/:tracking_tag_id
将跟踪标签从指定的行项目中解除关联。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必需 | 所使用账户的标识符。出现在资源的路径中，并且通常是所有广告主 API 请求的必需参数（GET accounts 除外）。指定的账户必须与已认证用户关联。 类型：字符串 示例： 18ce54d4x5t |
| tracking_tag_id 必需 | 本次请求中操作的跟踪标签的引用。 类型：字符串 示例： 555j |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j
示例响应
用户设置
GET accounts/:account_id/user_settings/:user_id
获取用户设置。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必需 | 所用账户的标识符。出现在资源的路径中，并且通常是所有广告主 API 请求的必需参数，除 GET accounts 外。 指定的账户必须与经过身份验证的用户关联。 类型：字符串 示例： 18ce54d4x5t |
| user_id 必需 | 请求中操作的用户 ID。使用 GET users/lookup 根据屏幕名称获取用户 ID。 类型：长整型 示例： 756201191646691328 |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328
示例响应
PUT accounts/:account_id/user_settings/:user_id
更新用户设置。需要用户上下文。帐户管理员无法访问。 资源 URLhttps://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id
参数
| 名称 | 描述 |
|---|---|
| account_id 必需 | 所用帐户的标识符。出现在资源的路径中以及 GET accounts。 指定的帐户必须与已认证的用户关联。 类型：字符串 示例： 18ce54d4x5t |
| user_id 必需 | 请求中操作的用户引用。使用 GET users/lookup 检索屏幕名称对应的用户 ID。 类型：长整型 示例： 756201191646691328 |
| notification_email 可选 | 用于帐户通知的电子邮件。 类型：字符串 示例： user@domain.com |
| contact_phone 可选 | 联系电话号码。 类型：字符串 示例： 202-555-0128 |
| contact_phone_extension 可选 | 联系 contact_phone 的分机号。 类型：字符串 示例： 1234 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='user@domain.com'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"
示例响应