# Ad Revenue Reports API

### About the API

The Ad Revenue Reports API is a Platform API, meaning it serves use cases spanning multiple products rather than being tied to just one. For example, the Criczop Cricket Feed API delivers cricket content and is a product-specific API for Criczop. In contrast, the Ad Revenue Reports API provides revenue data for your [entire Account ID, covering Property IDs](#user-content-fn-1)[^1] linked to various Zop products.

This API lets you query custom time ranges, apply filters, and select specific breakdowns.

***

### Making the request

#### API endpoint

<mark style="color:green;">`POST`</mark> `https://api.platform.gamezop.com/v1/ad-revenue-data`

{% hint style="info" %}
`POST` is used to allow complex filtering and payloads that may exceed standard `GET` query string limits.
{% endhint %}

#### Headers

<table><thead><tr><th width="190.25390625">Name</th><th width="150.03515625">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization: Bearer<mark style="color:red;">*</mark></td><td>String</td><td>Bearer token to authenticate requests. <br><br>You can find the Bearer token for this API under <em>Settings &#x26; Admin > API Tokens</em> within the Gamezop Business Dashboard. </td></tr><tr><td>Content-Type<mark style="color:red;">*</mark></td><td>String</td><td>Must be <code>application/json</code></td></tr></tbody></table>

#### Request body

{% hint style="info" %}
All dates must follow the `YYYY-MM-DD` format.
{% endhint %}

<table><thead><tr><th width="189.8828125">Name</th><th width="149.92578125">Type</th><th>Description</th></tr></thead><tbody><tr><td>start_date<mark style="color:red;">*</mark></td><td>String</td><td>Start date (inclusive). Must not be earlier than <code>2018-06-01</code>.</td></tr><tr><td>end_date<mark style="color:red;">*</mark></td><td>String</td><td>End date (inclusive). Cannot be in the future or earlier than <code>start_date</code>.</td></tr><tr><td>property_id</td><td>String</td><td><p>(Optional) Limits the data to a specific Property ID. If you don't pass anything, data is returned for all Properties under your Account.</p><p></p><p>More about Accounts and Properties <a href="../get-started/key-terms">here</a>.</p></td></tr><tr><td>metrics</td><td>String []</td><td><p>(Optional) Allows you to define which revenue-related metric(s) you want the API to return. These are the supported <code>metrics</code> values:</p><ul><li><a data-footnote-ref href="#user-content-fn-2">impressions</a></li><li><a data-footnote-ref href="#user-content-fn-3">clicks</a></li><li><a data-footnote-ref href="#user-content-fn-4">ctr</a></li><li><a data-footnote-ref href="#user-content-fn-5">ecpm</a></li><li><a data-footnote-ref href="#user-content-fn-6">revenue</a></li><li><a data-footnote-ref href="#user-content-fn-7">total-revenue</a></li></ul><p>If you do not pass any values in the API request body for this, we will return the following metrics by default: <code>impressions</code>, <code>ecpm</code>, and <code>revenue</code></p></td></tr><tr><td>breakdowns</td><td>String []</td><td><p>(Optional) Allows you to define how you want the revenue metrics to be broken down in the API response. <strong>You can pass multiple values, and all breakdowns will be applied.</strong> These are the supported <code>breakdowns</code> values:</p><ul><li><a data-footnote-ref href="#user-content-fn-8">date</a></li><li><a data-footnote-ref href="#user-content-fn-9">week</a></li><li><a data-footnote-ref href="#user-content-fn-10">month</a></li><li><a data-footnote-ref href="#user-content-fn-11">caap</a></li><li><a data-footnote-ref href="#user-content-fn-12">country</a></li><li><a data-footnote-ref href="#user-content-fn-13">ad-format</a></li><li><a data-footnote-ref href="#user-content-fn-14">product</a></li><li><a data-footnote-ref href="#user-content-fn-15">property-id</a></li></ul><p>If you do not pass any values in the API request body for this, we will apply the following breakdowns by default: <code>date</code> and <code>property-id</code></p></td></tr></tbody></table>

#### Sample request

Here's a sample cURL request:

```bash
curl --location 'https://api.platform.gamezop.com/v1/ad-revenue-data' \
--header 'Authorization: Bearer 88a514b4-d8d8-4ee6-afca-5bc9f316308a' \
--header 'Content-Type: application/json' \
--data '{
  "start_date": "2025-06-25",
  "end_date": "2025-06-30",
  "metrics": [
    "impressions",
    "clicks",
    "revenue",
    "total-revenue",
    "ctr",
    "ecpm"
  ],
  "breakdowns": [
    "property-id"
  ]
}'
```

***

### Understanding the response

The API provides a JSON response with an array of `data.ad_revenue` objects. Each report object will contain the metrics that you requested for, attributed to the combination of breakdowns you included in your request.

#### HTTP response codes

{% tabs %}
{% tab title="200: OK" %}
**Sample response body:**

{% code overflow="wrap" %}

```json
{
  "data": {
    "account_id": 123,
    "ad_revenue": [
      {
        "date": "2025-01-03",
        "week": "2024-12-30",
        "month": "2025-01-01",
        "country": {
          "code": 13,
          "name": "India"
        },
        "product":"quizzop",
        "impressions": 1000,
        "clicks": 150,
        "revenue": 21.157600
      },
      {
        "date": "2025-01-04",
        "week": "2024-12-30",
        "month": "2025-01-01",
        "country": {
          "code": 13,
          "name": "India"
        },
        "product":"quizzop",
        "impressions": 1200,
        "clicks": 200,
        "revenue": 30.250000
      }
    ]
  },
"success": true
}
```

{% endcode %}

**Notes on the response:**

* `data.account_id` is the Account ID mapped to your Bearer Token
* `data.ad_revenue` is an array of objects. Each object captures a set of breakdowns, and the ad revenue metrics against a combination of all those breakdowns. For instance, here's how you would read the *first* object from the sample response above:&#x20;

> *For 3rd January 2025 (which belongs to the week of 30th December 2024 and to the month of 1st January 2025), from your users visited Quizzop in India, your share of revenue was USD 21.157600. 1000 ad impressions were served to these users, and they clicked on the ads a total of 150 times.*
> {% endtab %}

{% tab title="400: Bad Request" %}
Here are the error messages you could receive:

* *Both start\_date and end\_date are required.*
* *start\_date cannot be after end\_date.*
* *start\_date or end\_date cannot be in the future (current time is calculated in UTC+05:30 timezone).*
* *start\_date cannot be before 2025-01-01, when caap breakdown is used.*
* *start\_date cannot be before 2018-06-01.*
* *Both start\_date and end\_date must be in YYYY-MM-DD format.*
* *Metrics passed in the request contain unsupported values. Please refer to our API docs to see the list of supported metrics: <https://gzp.gg/ad-revenue-data-api>.*
* *Breakdowns passed in the request contain unsupported values. Please refer to our API docs to see the list of supported breakdowns: <https://gzp.gg/ad-revenue-data-api>.*
  {% endtab %}

{% tab title="401: Unauthorized" %}
Here are the error messages you could receive:

* [*Invalid Bearer token*](#user-content-fn-16)[^16]*.*
* *The Property ID or IDs that you are requesting data for does not belong to the Account whose Bearer Token you have used.*
  {% endtab %}
  {% endtabs %}

***

### Other notes

* **The data returned by this API represents estimated earnings only and is not final.** If our systems detect invalid traffic (IVT) on your account, we reserve the right to deduct affected amounts prior to payment. Finalized earnings, net of any IVT deductions, can be tracked in the *Revenue Metrics > Payments* section of the Gamezop Business Dashboard.
* **All revenue data is recorded in the UTC+05:30 timezone (Asia/Kolkata)**. For example, if the API returns a revenue of USD 100 for the date `2025-01-01`, it corresponds to the time period from `2024-12-31 18:30:00 UTC` to `2025-01-01 18:30:00 UTC`
* When fetching revenue data for the current date, you may observe **frequent positive or negative fluctuations**. This can occur due to exchange rate variations and because ad networks typically take 24–48 hours from the time of revenue generation to report stable figures to us.
* **You don't need to pass your Account ID to us in the API request.** We find your Account ID using the Bearer Token you use for authorization.
* Revenue data is always returned with six-decimal precision and is denominated in USD.
* Note on dates:
  * Revenue data is available only for dates on or after 2018-06-01
  * CAAP breakdown data is available only for dates on or after 2025-01-01
  * Accurate country-level revenue data is available only from 2023-01-01 onward. For earlier dates, all revenue is reported under country ID `1179`, labeled as `Country breakdown unavailable (until 31 Dec 2022)`
* When you request a CAAP breakdown, the total revenue returned may be less than the total revenue reported without the CAAP breakdown. Read the note [here](https://docs.platform.gamezop.com/publishers/custom-ad-attribution-parameters#important-caveat) to learn why this happens.
* When you request a country breakdown, we report 2 values for each country: `id` and `name`. You can find a list of all supported country `id` and `name` values [here](https://docs.google.com/spreadsheets/d/1_AwQWAA6xJVG29E8073RlCGz4IVbzHVo4LC_JELBhiI/edit?usp=sharing).
* List of possible `ad_format` values:
  * display[^17]
  * interstitial[^18]
  * video[^19]
  * native[^20]
  * [additional - performance ads](#user-content-fn-21)[^21]
  * [additional - backfilled ads](#user-content-fn-22)[^22]
  * others[^23]
* List of possible `product` values:
  * gamezop
  * quizzop
  * astrozop
  * criczop
  * feedzop
  * events[^24]
  * performance-ads-reseller[^25]

[^1]: Learn more about Account ID and Property IDs [here](https://docs.platform.gamezop.com/publishers/get-started/key-terms).

[^2]: Total number of ad impressions shown to your users on Gamezop’s products.

[^3]: Total number of clicks that users made on the ads that were shown to them on Gamezop’s products.

[^4]: CTR stands for click-through rate. \
    \
    This is calculated as `{(clicks/impressions)*100}`. \
    \
    **Note:** We serve ads from a mix of multiple ad networks, and not all of them report clicks data to us. When calculating CTR, we only factor in impressions from those ad networks that report both clicks and impressions to us.

[^5]: eCPM stands for effective cost per mille.&#x20;

    This metric reflects the total revenue made (including Gamezop’s share of revenue) for every 1000 ad impressions. It is calculated as `{(revenue/impressions)*1000}`. \
    \
    **Note:** We serve ads from a mix of multiple ad networks, and not all of them report impressions data to us. When calculating eCPM, we only factor in revenue from those ad networks that report impressions data to us.

[^6]: Your share of advertising revenue from Gamezop’s products, captured in USD.

[^7]: Total advertising revenue, including Gamezop’s share, made on your Account. This is captured in USD.

[^8]: Break down revenue data by date.

[^9]: Break down data by week.&#x20;

    \
    The `week` field in the response always represents the Monday of the corresponding ISO week. Revenue is aggregated from Monday through Sunday.

[^10]: Break down data by month.&#x20;

    The `month` field always represents the first day of the corresponding ISO month.

[^11]: Break down data by [Custom Ad Attribution Parameters (CAAP)](https://docs.platform.gamezop.com/publishers/guides/custom-ad-attribution-parameters). Do not pass this breakdown unless you're using our CAAP functionality.\
    \
    See the [Other notes](#other-notes) section at the end of the page for more information.

[^12]: Break down data by country. See the [Other notes](#other-notes) section at the end of the page for a list of supported country codes.

[^13]: Break down data by the ad formats served to your users on our products. See the [Other notes](#other-notes) section at the end of the page for a list of all supported ad formats.

[^14]: Break down data by the Gamezop product where ads were served (such as Gamezop, Quizzop, etc.).\
    \
    See the [Other notes](#other-notes) section at the end of the page for a list of all possible `product` values.

[^15]: Break down data by your Property IDs.

[^16]: Occurs if the Bearer Token sent in the API request is invalid, or if you don't send a Bearer Token.

[^17]: Display ads served on our products, such as those of sizes 300x250, 320x50 and so on.

[^18]: Full page ads served on our products, such as Interstitial, Rewarded, Google Vignette and so on.

[^19]: Video / VAST ads served on our products.

[^20]: Native ads served on our products, outside of standard IAB sizes.

[^21]: Performance / affiliate ads served on our products. For these ads, we receive payments only on conversions, such as installs, sign ups, etc.\
    \
    We do not record impressions or clicks for this ad format.

[^22]: Ads served from Content Discovery Networks (such as but not limited to Taboola, MGID, Outbrain).\
    \
    We do not record impressions or clicks for this ad format.&#x20;

[^23]: Any other unclassified ad format. You would usually not see any significant portion of your revenue attributed to this ad format. If you do, please contact your Gamezop Account Manager and we'll look into it.

[^24]: Every Property ID in our system is mapped to a `product`. On the Gamezop Business Dashboard as well, you see your Property IDs grouped under different Zop products.\
    \
    `events` refers to seasonal products we create during festivals, sporting events, or other events of national / global importance. Our partners send traffic to these products only during such seasonal events.

[^25]: Only partners using [Gamezop Campaign Links](https://docs.platform.gamezop.com/publishers/integrate-performance-ad-campaigns/gamezop-campaign-links) will receive this `product` in their Ad Revenue Reports API.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform.gamezop.com/publishers/guides/ad-revenue-reports-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.