查询广告收入5分钟聚合数据
收藏接口说明
- 本接口为准实时接口。用户实际产生消耗后，相关数据会按 5 分钟粒度进行聚合，在聚合后对外返回，通常存在约 10～15 分钟延迟。
- 仅支持投放目标为「关键行为」和「变现 ROI」的广告数据通过本接口查询，其他类型广告数据不会计入统计。
- 由于部分归因策略暂不支持实时下发，接口返回的实时 cost 数据与小程序开发者后台结算单相比，可能存在约 5% 的误差，且误差比例可能会有波动。最终金额请以小程序开发者后台结算单为准。
使用限制
- 接口开放仅开放给特定类目小程序，具体见准入条件
- 本接口支持近3天ecpm数据（请开发者注意自行保存落库数据）
- 从接口查询速度及服务器压力考虑，建议开发者不要对同一时间周期同一用户进行反复数据获取，对于已经拉取过得周期、用户数据自行存储以后后续分析使用
基本信息
| 名称 | 描述 |
|---|---|
| HTTP URL | |
| HTTP Method | POST |
| Scope | ma.traffic.query |
请求参数
请求头
access-token必填String
示例：clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
content-type必填String
固定值"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
查询指定范围内数据，开始时间，支持跨天查询，字符串格式为：YYYY-MM-DD HH:mm、 或YYYY-MM-DD HH、或 YYYY-MM-DD，或 unix 时间戳，需与start_date 同时传入，优先级比date_hour高
时间区间按左闭右开 [start_date, end_date)
open_idString
示例：H2DH4z5rCM
用户OpenID，若不传该字段则查询所有用户
page_sizeInt32
示例：500
分页查询大小，若不传则默认500，最大值500
start_dateString
示例：start_date = 2026-05-01 14:50，end_date = 2026-05-01 14:58，返回event_time在时间区间 [2026-05-01 14:50, 2026-05-01 14:58)的数据，即 [14:50,14:55)和[14:55,15:00)的聚合数据。
查询指定范围内数据，开始时间，支持跨天查询，字符串格式为：YYYY-MM-DD HH:mm、 或YYYY-MM-DD HH、或 YYYY-MM-DD，或 unix 时间戳，需与end_date 同时传入，优先级比date_hour高。
时间区间按左闭右开 [start_date, end_date)
请求示例
curl --location 'https://open.douyin.com/dy_open_api/traffic/v3/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 | 参数不合法 | 根据错误信息检查请求参数是否填写正常 |
Q&A
1.查询无数据
ecpm接口返回无数据，可能为如下原因，有疑问请提雅典娜工单，【新版】如何从问问提交雅典娜工单
- •参数查询错误，openId、appId、日期等是否传对
- •查询超时：增加重试，请求密度控制在1-5分钟内一次，视网络、数据量定
- •广告未投放，投放目标需要为「关键行为」或「变现ROI」，参考巨量广告投放流程-投放流程指引-资产管理与创编IAA*抖音小程序-投放全流程指引
- •投【关键行为】，需要激活回传，参考巨量广告回传激活-投放流程指引-巨量回传IAA*抖音小程序-投放全流程指引。如果某个用户最近一个月无 clickid 激活记录（只看最新一次激活时间是否超过一个月，不管历史激活多少次），则无数据返回。
- •风控场景：非正常渠道的广告，用户近期内多次刷广告，识别到作弊场景
- •参数查询错误，openId、appId、日期等是否传对
- •查询超时：增加重试，请求密度控制在1-5分钟内一次，视网络、数据量定
接口缺失某些数据 的原因可能有：
- •用户通过客户端向广告服务端请求广告，但获取不到广告，此时客户端会展示兜底广告，兜底广告无收益也无数据。广告服务端是否返回广告是由广告策略决定。
- •用户获取和看到的广告为预览广告，即由预览广告计划产生的广告；这种情况通常是测试点击预览广告进入小程序的用户会获取到预览广告。
2.无用户登录记录（openid无效）
如果一个用户有多个帐号，用帐号A做了激活回传，用帐号B看了小程序内广告没有激活回传，ecpm数据会因为找不到帐号B的激活记录而归因到帐号A ，需开发者自行适配这种场景。
多帐号定义：同一设备在相同app端的不同帐号（多个抖音帐号）、不同app端的帐号（抖音账号和头条账号）。
