广告实时数据下发
收藏接口说明
- 仅支持投放为「关键行为」和「变现ROI」的广告数据支持通过接口查询，其他数据cost为0。
- 因部分归因策略暂无法实时下发，导致实时接口获取到的cost数据相较小程序开发者后台的结算单约多5%的数据误差，且此数值可能存在浮动变化，最终金额请以小程序开发者后台的结算单为准。
- 本接口是准实时的，即用户实际产生一笔消耗后，就会有对应的一条 cost 记录产生（可能会有几秒的延迟）。
- 可查询当天/当前小时的数据，且随着时间增长，返回的记录也会增长。
- 若查询过去小时和过去天的数据，由于时间已确定，返回的记录数已经固定，不会再增加。
使用限制
- 本接口的调用，当前已对短剧/工具类小程序开放，相关小程序可以直接调用。
- 本接口支持近3天ecpm数据（请开发者注意自行保存落库数据）
- 从接口查询速度及服务器压力考虑，建议开发者不要对同一时间周期同一用户进行反复数据获取，对于已经拉取过得周期、用户数据自行存储以后后续分析使用
基本信息
| 名称 | 描述 |
|---|---|
| HTTP URL | https://open.douyin.com/api/traffic/v2/rt_ecpm/query/ |
| HTTP Method | POST |
| Scope | ma.traffic.query |
请求参数
请求头
access-token必填String
示例：clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
content-type必填String
示例：application/json
固定值"application/json"
Body
cursorString
示例：0
分页查询游标，首次查询可不传，接口会返回next_cursor用于下次查询指定
date_hourString
示例：示例1：2023-11-30 则查询 [2023-11-30 00:00:00, 2023-12-01 00:00:00) 区间内的所有数据
示例2：2023-11-01 18 则查询 [2023-11-01 18:00:00, 2023-11-01 19:00:00) 区间的所有数据
格式：YYYY-MM-DD [HH]，若不传小时则查询当天所有数据
end_dateString
示例：示例3：start_date = "2024-02-29"，end_date = "2024-03-01 12"，则返回[2024-02-29 00:00:00, 2024-03-01 12:00:00) 时间段的数据
示例4：start_date = "2024-02-29 12"，end_date = "1709272800"，则返回 [2024-02-29 12:00:00, 2024-03-01 14:00:00) 时间段的数据
查询指定范围内数据，结束时间，支持跨天查询，字符串格式为：YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD HH:mm、 或YYYY-MM-DD HH、或 YYYY-MM-DD，或 unix 时间戳，
需与start_date同时传入，优先级比date_hour高
open_idString
示例：H2DH4z5rCM
用户OpenID，若不传该字段则查询所有用户
page_sizeInt32
示例：500
分页查询大小，若不传则默认500，最大值500
start_dateString
示例：示例1：start_date = 2024-02-29 14:52，end_date=2024-02-29 14:53，则返 回[2024-02-29 14:52, 2024-02-29 14:53)即14:52这一分钟内的数据
示例2：start_date = 2024-02-29 14:00，end_date = 2024-03-01 14:00，可以返回跨天时段的数据
查询指定范围内数据，开始时间，支持跨天查询，字符串格式为：YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD HH:mm、 或YYYY-MM-DD HH、或 YYYY-MM-DD，或 unix 时间戳，需与end_date 同时传入，优先级比date_hour高
请求示例
curl --location 'https://open.douyin.com/api/traffic/v2/rt_ecpm/query/' \ --header 'content-type: application/json' \ --header 'access-token: clt.8f7d76124da676ad57d4b92002c823dcdCYaIF0Y7L6sWqCo6d1izyOfRC3G_lq' \ --data '{"page_size":500,"start_date":"2024-02-29 14:52","end_date":"2024-02-29 14:53","open_id":"2BJ******IJ5","date_hour":"2023-11-30","cursor":"0"}'
响应参数
Body展开全部子属性
err_msg必填String
错误描述
err_no必填Int32
错误码
log_id必填String
请求唯一标识，方便追查问题
dataStruct
展开子属性
响应示例
正常响应示例异常响应示例
{ "data": { "records": [ { "id": "180", "mp_id": "tt123", "cost": "100", "open_id": "open_id_123", "event_time": "1698813481" } ], "next_cursor": "200" }, "err_no": "0", "err_msg": "success", "log_id": "202311301018036FC052BE3090CB55F5F1" }
切换单列布局错误码
| HTTP 状态码 | 错误码 | 错误码描述 | 排查建议 |
|---|---|---|---|
| 200 | 28001005 | 系统内部错误，请重试 | 请求重试，若依然无解请向平台提交反馈 |
| 200 | 28001003 | access_token无效 | 重新请求生成access_token |
| 200 | 28001008 | access_token过期,请刷新或重新授权 | 重新请求生成access_token |
| 200 | 28001016 | 当前应用已被封禁或下线 | clientKey被封禁或者下线 |
| 200 | 28001006 | 网络调用错误，请重试 | 重试即可 |
| 200 | 28001014 | 应用未授权任何能力 | 确认应用是否授权能力 |
| 200 | 28001018 | 应用未获得该能力 | 开通相关能力 |
| 200 | 28003017 | quota已用完 | 联系平台处理 |
| 200 | 28001019 | 应用该能力已被封禁 | 该能力被封禁，联系平台处理 |
| 200 | 28001007 | 参数不合法 | 根据错误信息检查请求参数是否填写正常 |
tips
使用建议
- 1.当接口返回时间超过5秒且报错时，较大可能是因为使用不指定open_id 且使用时间范围小于或等于15分钟 start_date 与 end_date 作为入参，建议指定 open_id 或使用 datehour 参数来查询，或者缩小 start_date 与 end_date 的时间范围，或者将 start_date 与 end_date 的时间范围增大超过15分钟（非兼容情况）。
- 2.使用cusor时，如果其他任一参数发生变更，cursor应该置空，否则 cursor 校验可能不通过，此时接口会返回第一页数据而导致不确定状态。
- 3.由于下游稳定性问题，如果open_id返回为空，可以在一定延迟后重新调用接口。
- 4.如果入参没有指定 open_id，且使用 start_date 与 end_date，且 start_date 与 end_date 的时间范围大于15分钟，则返回的记录按照 event_time 排序，这会导致某些延迟较大的记录会被游标跳过的情况。这种情况的实现是为了避免慢查询问题。如果使用这种参数组合，需要调用方使用多轮延迟查询来避免记录被游标跳过的情况，比如第一个定时任务调用前 15 分钟的数据，第一个定时任务调用前 30/60 分钟（或者更长）的来补充延迟大导致遗漏的数据。
查询无数据
接口返回无数据，可能为如下原因
- •广告未投放，参考巨量广告投放流程-投放流程指引-资产管理与创编IAA*抖音小程序-投放全流程指引
- •某个用户最近一个月无 clickid 激活记录（只看最新一次激活时间是否超过一个月，不管历史激活多少次），参考巨量广告回传激活-投放流程指引-巨量回传IAA*抖音小程序-投放全流程指引
- •风控场景：非正常渠道的广告，用户近期内多次刷广告，其它识别到的作弊场景
- •参数查询错误，openId、appId、日期等是否传对
- •查询超时：增加重试，请求密度控制在1-5分钟内一次，视网络、数据量定
接口缺失某些数据的原因可能有：
- •用户通过客户端向广告服务端请求广告，但获取不到广告，此时客户端会展示兜底广告，兜底广告无收益也无数据。广告服务端是否返回广告是由广告策略决定。
- •用户获取和看到的广告为预览广告，即由预览广告计划产生的广告；这种情况通常是测试点击预览广告进入小程序的用户会获取到预览广告。
与离线数据 gap 说明
gap 成因很多，例如实时数据源没有经过去重和风控机制。最终结算以离线数据为准。
接口响应报错处理
- 1.如果接口返回非零状态码且耗时低于5秒时，为上游鉴权服务稳定性问题，重试。
- 2.如果接口返回 28001005 状态码且耗时超过5秒时，为慢查询问题，参考使用建议。
- 3.其他情况重试。
cost返回为0
目前仅支持投放为「关键行为」和「变现ROI」的广告数据支持通过接口查询，其他数据会返回0
