Report API

中文 Open debug page

Overview

Query advertising system 1.0, system 2.0 or both through Report API V4. Versions V1–V3 remain available in the version selector.

Authorization

Each request should has authorization params in http query part.
Params Description
agent_id The access identifier, related to ad account, please contact us to get it.
secret_key The secret key, please contact us to get it.
And:
  • The API access frequency is limited to once per second.
  • Only in the IP whitelist can access the API, up to 3 IPs. Please contact us to add IPs.

Generic response structure

Field Description
code Response code, value 0 means success,more.
data Response data
message -

Get account list

GET
https://api.phoenix-ads.com/api/v4/ad/accounts
Get all of the related accounts, be used for get the report data.
Request params:
-
Response data:
Field Type Description
id number The account id
name string The account name
zone number The account timezone

Get report data

GET
https://api.phoenix-ads.com/api/v4/ad/account/:account_id/report
Get report data with account dimension,the account_id param in the API path should be the account id.
Report dates use the account timezone from zone in the account list. Names, creation time and creatives may be missing; metric rows are still returned. Metrics and event format follow V3.
Request params:
Field Name Type Default Description
system System source string all Use 1.0, 2.0 or all (default). 1.0 maps to is_new_system=0; 2.0 maps to is_new_system=1. With all, both sources are returned as separate rows in the same data array; metrics are not combined across sources. Send system, not is_new_system.
time_range Date range string - Required,json string {"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"},`since` and `until` means start time and end time.
breakdowns Break down fields string [] A JSON array string. System 1.0 dimensions: campaign_id, adset_id, ad_id. System 2.0 dimensions: campaign_id_2_0, ad_group_id, ad_id_2_0. Other supported dimensions: is_new_system, country, revenue_type, target_ad_type, hour, speed_dial_id. Unselected entity dimensions are aggregated. For all, you can request both sets of ID dimensions together.
campaign_id / adset_id / ad_id / fast_link_id / campaign_id_2_0 / ad_group_id / ad_id_2_0 Entity ID filters string - Filter by campaign_id, adset_id, ad_id, fast_link_id, campaign_id_2_0, ad_group_id or ad_id_2_0. Send a single ID as a decimal string, or multiple IDs as a JSON array string containing strings. Explicit ID filters take precedence over breakdown expansion. Never convert long IDs to JavaScript Number.
fields Response fields string [] A JSON array string; empty means all fields. ds, is_new_system and requested breakdown fields are retained even when fields is specified.
limit Data count limit number - Required,max to 2000
offset Data rows offset number - required,using limit and offset for paged data.
Response data:
Field Type Description
is_new_system string Source flag: 0 for system 1.0, 1 for system 2.0. Retained on every row, including queries with all.
campaign_id_2_0 string System 2.0 Campaign ID as a decimal string; request the corresponding breakdown dimension.
campaign_name_2_0 string System 2.0 Campaign name, when the corresponding business metadata is available.
ad_group_id string System 2.0 ad group ID as a decimal string; request the corresponding breakdown dimension.
ad_group_name string System 2.0 ad group name, when the corresponding business metadata is available.
ad_id_2_0 string System 2.0 ad entity ID as a decimal string; request the corresponding breakdown dimension.
ad_name_2_0 string System 2.0 ad name, taken from the creative used as the entity's primary material. May be missing.
ds string Date,YYYYMMDD-formatted
ad_id string Ad id
ad_name string Ad name. Uses legacy ad metadata when a valid legacy ad ID is present; otherwise uses the primary creative name of the system 2.0 entity.
ad_create_time string Ad creation time in YYYY-MM-DD HH:mm:ss format. Expand ad_id or ad_id_2_0, or filter by the ad explicitly. Uses the original database time without conversion to the account timezone.
creatives array Actual creatives used by the ad, with creative_id, type (IMAGE / VIDEO), url and optional video_cover. Uses legacy creatives when a valid legacy ad ID exists; otherwise uses the system 2.0 entity's primary material and icon. Other materials in the ad group's pool are excluded. May be empty or missing.
adset_id string Set id
adset_name string Set name
campaign_id string Campaign id
campaign_name string Campaign name
cash_cost string Cash cost
gift_cost string Gift cost
click number Click count
event string Url-encoded content,each key means event name, value means event count.
optimization_event string The optimization event name, only present when `adset_id` in breakdowns.
impression number Impression count
install number Install count
click_url string Landing url

Other optional dimensions include country, hour, revenue_type, target_ad_type, speed_dial_id and speed_dial_name. Presence depends on requested dimensions and available data.

paging (object) — Pagination: total is the number of matching rows, limit is the maximum rows returned in this page, and offset is the starting offset. Increase offset for subsequent pages.

Response code

Code Description
0 Success
2600 Data not ready
4000 Parameters error
4100 Unauthorized
4300 No permission
4400 API not found
4800 Access ip not authorized
4900 Request frequency capped
5000 Internal error

Demo

Using Javascript:
                    const apiHost = 'https://api.phoenix-ads.com';

// authorization params in the http query part
const authParams = {
  agent_id: 'YOUR_AGENT_ID',
  secret_key: 'YOUR_SECRET_KEY'
};

// example response data for account list
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');
}

// request params,notice that time_range、breakdowns、fields need convert to json string
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));

// the account id is in the url path
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);

// example response data for report
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 }
};