Report API
中文 Open debug pageOverview
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 }
};