Report API

中文

Overview

The Phoenix Ads platform's Report API,get account's ad data using http request.

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/v2/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/v2/ad/account/:account_id/report
Get report data with account dimension,the account_id param in the API path should be the account id.
Request params:
Field Name Type Default Description
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 [] An Array string, Optional value: campaign_id、adset_id and ad_id,means break down Campaign、Set and Ad.
fields Response fields string [] Default to get all fields, can be set to the fields below
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
ds string Date,YYYYMMDD-formatted
ad_id string Ad id
ad_name string Ad name
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

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: '1234567890',
  secret_key: '1234567890'
};

// SOME_FETCH_LIB means the fetch library
const accountRes = await SOME_FETCH_LIB.get(`${apiHost}/api/v2/ad/accounts`, authParams);

// example response data for account list
const accountResDemo = {
  code: 0,
  data: [
    {
      id: 1,
      name: 'Test Account',
      zone: 8
    }
  ]
}

// request params,notice that time_range、breakdowns、fields need convert to json string
const reportParams = {
  ...authParams,
  time_range: JSON.stringify({since: '2023-01-01', until: '2023-02-01'}),
  breakdowns: JSON.stringify(['campaign_id']),
  fields: JSON.stringify([]),
  limit: 100,
  offset: 0
};

// the account id is in the url path
const reportRes = await SOME_FETCH_LIB.get(`${apiHost}/api/v2/ad/account/${accountRes.data[0].id}/report`, reportParams);

// example response data for report
const reportResDemo = {
  code: 0,
  data: [
    {
      "ad_id": "123456",
      "ad_name": "Test Ad",
      "adset_id": "123456789",
      "adset_name": "Test Ad set",
      "campaign_id": "1234567890123456",
      "campaign_name": "Test Campaign",
      "cash_cost": "0.00000000",
      "click": 0,
      "ds": "20230201",
      "event": "Registration=12",
      "gift_cost": "0.00000000",
      "impression": 0,
      "install": 0
    }
  ]
}