Ad Report API

Summary Report API

API Description

Data Update Frequency:
- Non-geo dimensions: Every 15-30 minutes.
- Geo dimensions: Over 1 hour.
QPM (Queries Per Minute) Limit:
- Limit is set to 10. If requests exceed 10 times in one minute, a "Too Many Requests" error will be returned. You need to wait until the next minute to make another request.

Data Time Zone for Various Media Channels:

Channel	Data Time Zone
Meta	Ad Account Time Zone
Google	Ad Account Time Zone
TikTok	Ad Account Time Zone
Kwai	UTC+0
Apple Search Ads	Ad Account Time Zone
Petal Ads	Ad Account Time Zone
Mintegral	Ad Account Time Zone
AppLovin	UTC+0
Unity	UTC+0
ironSource	UTC+0
Liftoff Direct	UTC+0

API Path
- POST https://xmp-open.mobvista.com/v2/media/account/report

Request Parameters

Parameter	Type	Required	Description
client_id	string	Y	Please contact your admin or sub-admin to obtain it and ensure Open API permissions have been activated.
timestamp	int	Y	UNIX timestamp at the time of the request.
sign	string	Y	md5 hash of (client_secret + timestamp).
start_date	string	Y	Format: YYYY-MM-DD
end_date	string	Y	Format: YYYY-MM-DD
dimension	[]string	N	By default, data is returned at the dimension of the ad account ID, for example: ['date']. Optional values include: date (Date) geo (Region, data for this dimension will be delayed by more than 1 hour on the day) account_name (Ad Account Name) campaign_id (Campaign ID) campaign_name (Campaign Name) adset_id (Ad Set ID) adset_name (Ad Set Name) ad_id (Ad ID) ad_name (Ad Name) product_id (Product ID) product_name (XMP Product Name) os (Operating System) store_package_id (Store ID) Note: When querying data at the XMP product dimension, it is necessary to first associate the ad campaigns with the XMP products in the backend.
metrics	[]string	Y	Metrics to retrieve, obtained from the Query Available Metrics API.
module	string	N	Media channel, see Enum Value.
account_id	[]string	N	Ad account IDs.
campaign_id	[]string	N	Campaign IDs.
adset_id	[]string	N	Ad set IDs.
ad_id	[]string	N	Ad IDs.
geo	[]string	N	Two-letter country codes, e.g., CN.
product_id	[]int	N	Product IDs.
third_party_timezone	string	N	Time zone for third-party data metrics, see Enum Value. Note: When the time zone switch for third-party metrics is enabled in the XMP backend, this field must be specified when retrieving third-party metrics via the API.
currency	string	N	If not specified, the currency of the media side's advertising account will be returned. Options include: CNY, USD, EUR (compatible with all lowercase).
page	int	Y	Page number. If the returned `data.list` is not empty, please increment the page number by 1 to continue retrieving the next page's content, until `data.list` is empty.
page_size	int	N	Number of records per page, range 1-1000, default 200.

Request Example

let dimension = ["date"];
let request = {
    url: uri,
    method: 'POST',
    header: {'Content-Type': 'application/json'},
    body: {
        mode: 'raw',
        raw: JSON.stringify({
            client_id: clientId,
            module: "applovin",
            timestamp: timestamp,
            sign: sign,
            start_date: startDate,
            end_date: endDate,
            dimension: dimension,
            product_id: [62164],
            geo: ["US", "KR"],
            metrics: ["click", "cost"],
            page: page,
            page_size: page_size,
            currency: currency,
            third_party_timezone: "+8"
        }),
        options: {
            raw: {
                language: 'json'
            }
        }
    }
}

Return Parameters

Parameter	Type	Description
list	[]object	List of returned data records.
page	object	Pagination information.
page.page	int	Current page number.
page.page_size	int	Number of records per page.

Attributes/Dimensions in the list:

Parameter	Type	Description
date	string	Date
module	string	Media channel
account_id	string	Ad account ID
account_name	string	Ad account name
campaign_id	string	Campaign ID
campaign_name	string	Campaign name
adset_id	string	Ad set ID
adset_name	string	Ad set name
ad_id	string	Ad ID
ad_name	string	Ad name
product_id	int	Product ID
product_name	string	XMP product name
os	string	Application platform
store_package_id	string	Store ID
geo	string	Region
timezone	string	Time zone of the ad account in media
currency	string	Priority is given to the currency set at the time of the request, when no currency is set, the currency of the account on the media side is returned.

Return Example

{
    "code": 0,
    "msg": "success",
    "data": {
        "list": [
            {
                "account_id": "aaa",
                "click": 557132,
                "cost": 2613.75,
                "date": "2024-01-02",
                "module": "applovin",
                "product_name": "S",
                "solar_engine_real_install": 0,
                "timezone": ""
            }
        ],
        "page": {
            "page": 1,
            "page_size": 1,
            "next_page": 1
        }
    }
}

Query Available Metrics API

API Description
- QPM (Queries Per Minute) Limit:
  - Limit is set to 120. If requests exceed 120 times in one minute, a "Too Many Requests" error will be returned. You need to wait until the next minute to make another request.
API Path
- POST https://xmp-open.mobvista.com/v1/media/report/fields

Request Parameters

Parameter	Type	Required	Description
client_id	string	Y	Please contact your admin or sub-admin to obtain it and ensure Open API permissions have been activated.
timestamp	int	Y	UNIX timestamp at the time of the request.
sign	string	Y	md5 hash of (client_secret + timestamp).
report_type	string	Y	Query available metrics for the Ad Report API: `ad` Query available metrics for the Creative Report API: `material`

Header Field:
Field Description
Accept-Language
To return metrics with their names in English: en-US

Field	Description
Accept-Language	To return metrics with their names in English: `en-US`

Request Example

let request = {
    url: uri,
    method: 'POST',
    header: {'Content-Type': 'application/json', 'Accept-Language': 'en-US'},
    body: {
        mode: 'raw',
        raw: JSON.stringify({
            client_id: clientId,
            timestamp: timestamp,
            sign: sign,
            report_type: "material" // or 'ad'
        }),
        options: {
            raw: {
                language: 'json'
            }
        }
    }
}

Return Parameters

Parameter	Type	Description
report_type	string	Query available metrics for the Ad Report API: `ad` Query available metrics for the Creative Report API: `material`
fields	[]object	List of available metrics.
fields.field	string	Metric ID. To query this metric, you can pass this value into the `metrics` field of the report API.
fields.title	string	Metric name.
fields.format	string	Format of the metric, e.g., 'integer'.
fields.source	string	Source of the metric.

Return Example

{
    "code": 0,
    "msg": "success",
    "data": {
        "report_type": "material",
        "fields": [
            {
                "field": "impression",
                "title": "Impression",
                "format": "integer",
                "source": "channel"
            },
            {
                "field": "postback_install",
                "title": "Third-party Conversions",
                "format": "integer",
                "source": "xmp"
            },
            {
                "field": "af_conversion",
                "title": "Install",
                "format": "",
                "source": "appsflyer"
            },
            {
                "field": "adjust_conversion",
                "title": "Conversion",
                "format": "integer",
                "source": "adjust"
            },
            {
                "field": "solar_engine_real_install",
                "title": "Install",
                "format": "integer",
                "source": "solar_engine"
            },
            {
                "field": "tenjin_tracked_installs",
                "title": "Installs",
                "format": "integer",
                "source": "tenjin"
            }
        ]
    }
}

Open API Protocol

Creative Report API

Last modified: 2024-12-12Powered by

Outline