How to use AdButler's Reporting API
AdButler's Reporting API lets you gather your ad serving statistics and use them however you choose. You can make your own dashboard, generate reports, or track the performance of only certain publishers or advertisers.
Requesting via GET
There are many parameters that you can add to your GET request, some of which are required. As previously noted, the full list and details about the parameters are in our API documentation. There are however notable parameters that may not seem intuitive at first glance.
type: overview
type is a required parameter that tells our server the subject of the data you want to retrieve. The overview value will retrieve data from all publishers in your account.
Along with type, you can further limit the scope of the data in the response by specifying the IDs of your desired publisher, zone, advertiser, campaign, or ad item.
summary
This is a boolean that indicates if your ads' fundamental statistics - such as impressions, clicks, and revenue - should be included in the response.
details
This is a boolean that indicates if the backend details of your ad serving setup - such as start and end dates, ad item IDs and placement IDs - should be included in the response.
breakdown
This is a boolean that indicates if the information in summary and details should be separated per ad item served.
financials
This is a boolean that indicates if cost- and profit-related information - such as payout, revenue, and eCPM - should be included in the response. Note that these data will already be included if summary is set to true. This parameter simply gives you the option to obtain ONLY financial information if you set summary to false.
limit
By default, our server will return up to 10 records per request sequentially. However, in some endpoints, you can use the limit parameter to adjust the number of records returned per request. You can set it to any integer, including values greater than 10.
If there are records further down the line that are covered by the filters you set in your request but were not included in the response, the has_more parameter in the response will be set to true.
offset
By default, our server will return up to 10 records per request sequentially. However, in some endpoints, you can use the offset parameter to skip records and start from a particular one. You can set it to any positive integer.
If there are records further down the line that are covered by the filters you set in your request but were not included in the response, the has_more parameter in the response will be set to true.
Example request and response
Request:
https://api.adbutler.com/v2/reports?type=zone&period=week&preset=last-week&timezone=America/Los_Angeles&zones=123456&summary=true&details=true&breakdown=true&financials=true
Response:
"object": "report",
"url": "/v2/reports",
"data": [
{
"type": "zone",
"id": 123456,
"summary": {
"responses": 1002,
"impressions": 1002,
"eligible_impressions": 950,
"viewable_impressions": 892,
"clicks": 0,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0,
"financials": {
"cost": [],
"payout": [],
"revenue": [],
"e_cpm": [],
"e_cpc": [],
"e_cpa": []
},
"breakdown": [
{
"ad_item": {
"type": "image_ad_item",
"id": 123456
},
"advertiser": 123456,
"campaign": {
"type": "standard_campaign",
"id": 123456
},
"clicks": 0,
"conversions": 0,
"cost": 0,
"e_cpa": 0,
"e_cpc": 0,
"e_cpm": 0,
"eligible_impressions": 497,
"financials": {
"cost": [],
"payout": [],
"revenue": [],
"e_cpm": [],
"e_cpc": [],
"e_cpa": []
},
"impressions": 513,
"payout": 0,
"placement": 123456,
"popup": null,
"publisher": 123456,
"responses": 513,
"revenue": 0,
"text_ad": null,
"viewable_impressions": 464,
"zone": {
"type": "standard_zone",
"id": 123456
}
},
{
"ad_item": {
"type": "image_ad_item",
"id": 123456
},
"advertiser": 123456,
"campaign": {
"type": "standard_campaign",
"id": 123456
},
"clicks": 0,
"conversions": 0,
"cost": 0,
"e_cpa": 0,
"e_cpc": 0,
"e_cpm": 0,
"eligible_impressions": 453,
"financials": {
"cost": [],
"payout": [],
"revenue": [],
"e_cpm": [],
"e_cpc": [],
"e_cpa": []
},
"impressions": 489,
"payout": 0,
"placement": 123456,
"popup": null,
"publisher": 123456,
"responses": 489,
"revenue": 0,
"text_ad": null,
"viewable_impressions": 428,
"zone": {
"type": "standard_zone",
"id": 123456
}
}
]
},
"details": [
{
"start_date": "2022-02-20T00:00:00-08:00",
"responses": 1002,
"impressions": 1002,
"eligible_impressions": 950,
"viewable_impressions": 892,
"clicks": 0,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0,
"financials": {
"cost": [],
"payout": [],
"revenue": [],
"e_cpm": [],
"e_cpc": [],
"e_cpa": []
},
"breakdown": [
{
"ad_item": {
"type": "image_ad_item",
"id": 123456
},
"advertiser": 123456,
"campaign": {
"type": "standard_campaign",
"id": 123456
},
"clicks": 0,
"conversions": 0,
"cost": 0,
"e_cpa": 0,
"e_cpc": 0,
"e_cpm": 0,
"eligible_impressions": 497,
"financials": {
"cost": [],
"payout": [],
"revenue": [],
"e_cpm": [],
"e_cpc": [],
"e_cpa": []
},
"impressions": 513,
"payout": 0,
"placement": 123456,
"popup": null,
"publisher": 123456,
"responses": 513,
"revenue": 0,
"text_ad": null,
"viewable_impressions": 464,
"zone": {
"type": "standard_zone",
"id": 123456
}
},
{
"ad_item": {
"type": "image_ad_item",
"id": 123456
},
"advertiser": 123456,
"campaign": {
"type": "standard_campaign",
"id": 123456
},
"clicks": 0,
"conversions": 0,
"cost": 0,
"e_cpa": 0,
"e_cpc": 0,
"e_cpm": 0,
"eligible_impressions": 453,
"financials": {
"cost": [],
"payout": [],
"revenue": [],
"e_cpm": [],
"e_cpc": [],
"e_cpa": []
},
"impressions": 489,
"payout": 0,
"placement": 123456,
"popup": null,
"publisher": 123456,
"responses": 489,
"revenue": 0,
"text_ad": null,
"viewable_impressions": 428,
"zone": {
"type": "standard_zone",
"id": 123456
}
}
]
}
]
}
],
"meta": {
"type": "zone",
"period": "week",
"from": "2022-02-20T00:00:00-08:00",
"to": "2022-02-27T00:00:00-08:00",
"timezone": "America/Los_Angeles"
}
