Report API
English 打开调试页概述
通过 V4 Report API 查询广告 1.0、2.0 或全部来源的数据。V1–V3 仍可在版本选择器中访问。
请求鉴权
所有请求都需要带上鉴权参数,位于 http 请求 query 部分
| 参数 | 描述 |
|---|---|
| agent_id | 接入身份标识,与广告账户绑定,请联系我们获取 |
| secret_key | 密钥,请联系我们获取 |
另外:
- 接口访问频率限制为 1次/秒
- 仅限ip白名单内的地址能访问接口,最多 3 个ip,请联系我们授权访问ip
通用返回结构
| 字段 | 说明 |
|---|---|
| code | 返回码,0表示成功,详见下方 |
| data | 返回结果 |
| message | - |
获取账户列表
GET
https://api.phoenix-ads.com/api/v4/ad/accounts
获取对应的账户信息,可用于后续请求报告传入账户id
请求参数:
-
返回结果:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | number | 账户 id |
| name | string | 账户名 |
| zone | number | 账户时区 |
获取账户报告
GET
https://api.phoenix-ads.com/api/v4/ad/account/:account_id/report
以广告账户维度获取报告数据,接口地址account_id参数为上面获取到的账户id
报告日期按账户时区统计,以账户列表中的 zone 为准。名称、创建时间、素材可能缺失,缺失时仍返回指标。本期指标及事件格式沿用 V3。
请求参数:
| 字段 | 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| system | 系统来源 | string | all | 可选 1.0、2.0、all,默认 all。1.0 对应 is_new_system=0,2.0 对应 is_new_system=1;all 在同一个 data 数组中分别返回两种来源,不跨来源合并指标。调用方只需传 system,无需传 is_new_system。 |
| time_range | 查询范围 | string | - | 必填,json字符串 {"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"},since和until即开始和结束时间 |
| breakdowns | 细分字段 | string | [] | JSON 数组字符串。1.0 维度:campaign_id、adset_id、ad_id;2.0 维度:campaign_id_2_0、ad_group_id、ad_id_2_0。其他可选维度:is_new_system、country、revenue_type、target_ad_type、hour、speed_dial_id。未选择的实体维度默认汇总;查询 all 时可同时传入两套 ID 维度。 |
| campaign_id / adset_id / ad_id / fast_link_id / campaign_id_2_0 / ad_group_id / ad_id_2_0 | 实体 ID 筛选 | string | - | 可按 campaign_id、adset_id、ad_id、fast_link_id、campaign_id_2_0、ad_group_id、ad_id_2_0 筛选。单个 ID 传十进制字符串;多个 ID 传由字符串组成的 JSON 数组字符串。显式 ID 筛选优先于 breakdowns 展开。长 ID 不要转成 JavaScript Number。 |
| fields | 返回字段 | string | [] | JSON 数组字符串,默认返回全部字段。指定 fields 时,仍保留 ds、is_new_system 和 breakdowns 对应字段。 |
| limit | 数据条数限制 | number | - | 必填,最大不超过2000 |
| offset | 数据偏移量 | number | - | 必填,结合limit与offset可实现分页 |
返回结果:
| 字段 | 类型 | 说明 |
|---|---|---|
| is_new_system | string | 来源标记,0 为 1.0、1 为 2.0;每行保留该标记,用于区分 all 返回的数据。 |
| campaign_id_2_0 | string | 2.0 Campaign ID,十进制字符串;需要在 breakdowns 中展开对应维度。 |
| campaign_name_2_0 | string | 2.0 Campaign 名称,查询到对应业务信息时返回。 |
| ad_group_id | string | 2.0 广告组 ID,十进制字符串;需要在 breakdowns 中展开对应维度。 |
| ad_group_name | string | 2.0 广告组名称,查询到对应业务信息时返回。 |
| ad_id_2_0 | string | 2.0 广告实体 ID,十进制字符串;需要在 breakdowns 中展开对应维度。 |
| ad_name_2_0 | string | 2.0 广告名称,取实体实际主素材对应的创意名称,查不到时可缺失。 |
| ds | string | 时间,YYYYMMDD格式 |
| ad_id | string | 广告 id |
| ad_name | string | 广告名称。有有效旧广告 ID 时使用原广告名称,否则使用 2.0 实体的主素材创意名称。 |
| ad_create_time | string | 广告创建时间,YYYY-MM-DD HH:mm:ss。需展开 ad_id 或 ad_id_2_0,或显式筛选对应广告;沿用数据库原始时间,不随账户时区转换。 |
| creatives | array | 广告实际关联的素材数组,包含 creative_id、type(IMAGE / VIDEO)、url、可选 video_cover。使用有效旧广告 ID 时沿用旧素材;否则补充 2.0 实体实际使用的主素材和图标。不返回广告组内未被该实体使用的素材;查不到时可为空或缺失。 |
| adset_id | string | 广告Set id |
| adset_name | string | 广告Set名 |
| campaign_id | string | 广告Campaign id |
| campaign_name | string | 广告Campaign名 |
| cash_cost | string | 实际花费 |
| gift_cost | string | 赠金花费 |
| click | number | 点击量 |
| event | string | urlEncode形式的内容,其中key为深度事件名称,value为深度事件数量 |
| optimization_event | string | 优化事件名称,需 set 展开后才返回 |
| impression | number | 曝光量 |
| install | number | 下载量 |
| click_url | string | 广告链接 |
其他可选维度字段包括 country、hour、revenue_type、target_ad_type、speed_dial_id、speed_dial_name;是否返回取决于查询维度及数据是否存在。
paging (object) — 分页信息:total 为当前查询的总条数;limit 为本次返回的条数上限;offset 为起始偏移。增大 offset 可继续查询。
返回码
| 返回码 | 说明 |
|---|---|
| 0 | 成功 |
| 2600 | 数据未准备好 |
| 4000 | 参数错误 |
| 4100 | 鉴权失败 |
| 4300 | 无权限 |
| 4400 | 接口不存在 |
| 4800 | 请求 ip 未授权 |
| 4900 | 请求频率超限制 |
| 5000 | 内部错误 |
完整请求示例
以 Javascript 语言为例:
const apiHost = 'https://api.phoenix-ads.com';
// 全局鉴权参数,位于请求query部分
const authParams = {
agent_id: 'YOUR_AGENT_ID',
secret_key: 'YOUR_SECRET_KEY'
};
// 账户返回示例
const accountsUrl = new URL('/api/v4/ad/accounts', apiHost);
accountsUrl.search = new URLSearchParams(authParams).toString();
const accountRes = await (await fetch(accountsUrl)).json();
if (accountRes.code !== 0 || !accountRes.data?.length) {
throw new Error(accountRes.message || 'No accessible accounts');
}
// 构造请求参数,注意time_range、breakdowns、fields参数需要转为json字符串
const reportParams = {
...authParams,
system: '2.0',
time_range: JSON.stringify({since: '2026-10-20', until: '2026-10-20'}),
breakdowns: JSON.stringify(['campaign_id_2_0', 'ad_group_id', 'ad_id_2_0']),
fields: JSON.stringify([]),
limit: 100,
offset: 0
};
await new Promise(resolve => setTimeout(resolve, 1100));
// url带入账户id查询报告
const reportUrl = new URL(`/api/v4/ad/account/${accountRes.data[0].id}/report`, apiHost);
reportUrl.search = new URLSearchParams(reportParams).toString();
const reportRes = await (await fetch(reportUrl)).json();
console.log(reportRes);
// 报告返回示例
const reportResDemo = {
code: 0,
data: [
{
"ds": "20261020",
"is_new_system": "1",
"campaign_id_2_0": "6648000000000000001",
"campaign_name_2_0": "Test Campaign 2.0",
"ad_group_id": "6648000000000000002",
"ad_group_name": "Test Ad Group 2.0",
"ad_id_2_0": "6648000000000000003",
"ad_name_2_0": "Test Creative",
"ad_name": "Test Creative",
"ad_create_time": "2026-10-19 10:00:00",
"creatives": [
{ "creative_id": "998877", "type": "IMAGE", "url": "https://example.com/a.png" }
],
"cash_cost": "1.23000000",
"gift_cost": "0.00000000",
"impression": 100,
"click": 5,
"install": 0,
"event": "Registration=2&Deposit=1"
}
],
paging: { total: 1, limit: 1, offset: 0 }
};