How to use AdButler's Reporting API

This guide is an overview on using AdButler's Reporting API. For details on the reporting endpoints themselves, read our API documentation.

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"
}

Can't find what you're looking for?

Send us an email

hello@adbutler.com

Visit the blog

For more ad serving tips, industry news and AdButler insights.