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 }
};