Reporting API - Advertiser

Last updated: 12/11/2024

Overview

As an Advertiser, you can use the Reporting API to retrieve reporting data for your ads that are served in the Offerwall.

Before you begin: You must authenticate with the API, following the steps here.

For information on how to manage your campaigns through the Reporting API, see Campaign Management.
For information on error handling and limitations with the Reporting API, see Reporting API Best Practices.

Advertiser Reporting Metrics

The Reporting API can be used to request performance data for your ad sets and multi-reward events, including metrics such as revenue, impressions, and conversions. All available advertiser reporting metrics are listed in the chart below.

We recommend advertisers to start with the following base query to retrieve performance metrics:

query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timeRange: {from: "YYYY-MM-DDT00:00:00Z", until: "YYYY-MM-DDT00:00:00Z"}) {
      timestamps
      reports {
        impressions
      }
    }
  }
}

Advertiser Metric	Description
amount	Bid for this event
averageBid	Total Spend divided by Total Conversions
callToActionClicks	The number of times users clicked the call-to-action, if a call-to-action is present
clickToConversionTime	Click to conversion time data segmented in several different ways. Note: CTCT metrics are only reported in the 1st UTC hour of every day. When using a granularity of `HOURLY`, only the hour representing `00:00:00 UTC - 00:59:59 UTC` will have a value other than 0.
conversions	Number of conversions for the ad objective
csConversions	Number of Customer Service conversions for the ad objective
csSpend	Total Customer Support amount spent
ecpi	Total Spend divided by Total Engagements
engagementInstalls	The number of installs inferred from engagements
impressions	The number of times the ad was clicked on in the offerwall. Note: This metric more accurately represents `clicks`, not `impressions`. We will be renaming this metric soon.
offerwallAverageRank	The (weighted) average offerwall position the ad was served in. The value is ascending from 1, with 1 representing the top spot in the offerwall. A value of 0 means the offer was not displayed in the offerwall for the selected time period
offerwallImpressions	The number of times the ad appeared in the offerwall. Note: An ad can appear in the offerwall and not be viewed by a user (i.e. user has not scrolled far enough to see the ad). We recommend Advertisers to use `offerwallTrueImpressions` below.
offerwallTrueImpressions	The number of times the ad was viewed by a user in the offerwall. Each view registers as a true impression.
returnOnAdSpend	Return on ad spend data for users who installed on each day. Note: Return on ad spend metrics are only reported in the 1st UTC hour of every day.
dayXRoas	Total return on ad spend `X` days from install. This is calculated as `day_X_roas_revenue` divided by `day_X_roas_spend`. If `day_X_roas_revenue` is 0, this field will also be 0. Available for `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`.
dayXRoasAdRevenue	Total user ad revenue `X` days from install. Available for `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`.
dayXRoasEngagements	Total user engagements `X` days from install. Available for `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`.
dayXRoasIapRevenue	Total user IAP revenue `X` days from install. Available for `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`.
dayXRoasRevenue	Total user revenue `X` days from install. This is calculated as `day_X_roas_iap_revenue` plus `day_X_roas_ad_revenue`. Available for `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`.
dayXRoasSpend	Total advertiser spend `X` days from install. Available for `X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90`.
spend	Total amount spent

Additional Advertiser Metrics available in the Dashboard

Conversion Rate (CVR)
Instruction CVR
Conversions/Impressions
Click-through Rate (CTR)
ROAS by Total Spend (the Reporting API returns ROAS by Cohorted Spend)

Metric Segmentations

By adding segment fields to your queries, the API can return performance data broken down by event, publisher app, country, etc. The Reporting API supports segmentation under the following breakdowns:

country
attributionSource
language
platform
id (Publisher App ID)
id (AdSet/Offer ID)
multiRewardEngagementEvent

Segmentation Examples

Segment by Country, Attribution Source, and/or Language

Query

Result

{
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timeRange: {from: "2024-08-01T00:00:00Z", until: "2024-08-01T11:59:59Z"}, timeIncrement: DAILY) {
      timestamps
      reports {
        country
        attributionSource
        language
        conversions
      }
    }
  }
}

Segment by Platform

Query

Result

{
  advertiser{
    id
    campaigns(first: 2){
      nodes{
        insights{
          reports{
            impressions
            platform
          }
        }
      }
    }
  }
}

Segment by Publisher App

Query

Result

query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    ads {
      id
      insights(timePreset: TODAY) {
        reports {
          app {
            bundleId
          }
          impressions
          conversions
          spend
        }
      }
    }
  }
}

Segment by Ad Set/Campaign

Query

Result

query {
  advertiser {
    adSets(first: 50, configuredStatus: ACTIVE) {
      edges {
        node {
          id
          insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-16T00:00:00Z"}) {
            timestamps
            reports {
              conversions
              spend
            }
          }
        }
      }
    }
  }
}

Segment by Multi-Reward Engagement Event

Query

Result

{
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    id
    insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-15T11:59:59Z"}, timeIncrement: DAILY) {
      timestamps
      reports {
        conversions
        returnOnAdSpend {
          day0Roas
        }
        multiRewardEngagementEvent {
          eventName
        }
      }
    }
  }
}

Filtering Capabilities

By adding filters to your queries, the API will return performance metrics from the specified sources only. The Reporting API supports the following filtering capabilities:

adSet (Single Ad Set)
adSets (Multiple Ad Sets)
appIds (Publisher App)
configuredStatus (ACTIVE, ARCHIVED, or PAUSED)
countries
timePreset
timeRange

Filtering Examples

Filter by Ad Set

This limits results to a single adSet

query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timeRange: {from: "2024-08-06T00:00:00Z", until: "2024-08-07T00:00:00Z"}) {
      timestamps
      reports {
        impressions
        conversions
        spend
        offerwallAverageRank
      }
    }
  }
}

Filter for Multiple Ad Sets

This limits results to the first or last x Ad Sets

query {
  advertiser {
    adSets(first: 2) {
      edges {
        node {
          insights(timePreset:TODAY) {
            reports {
              conversions
            }
          }
        }
      }
    }
  }
}

Filter by Publisher App

This limits results to the specified publisher app IDs

query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(filter:{appIds: ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000000"]}) {
      timestamps
      reports {
        conversions
      }
    }
  }
}

Filter by Configured Status

This limits results to the ad sets/campaigns with the specified status

Options: ACTIVE, ARCHIVED, or PAUSED

query {
  advertiser {
    adSets(first: 2, configuredStatus: ACTIVE) {
      edges {
        node {
          insights(timePreset:TODAY) {
            reports {
              conversions
            }
          }
        }
      }
    }
  }
}

Filter by Country

This limits results to the specified countries

query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(filter:{countries: [JP, US]}) {
      timestamps
      reports {
        conversions
      }
    }
  }
}

Filter by a Preset Timeframe

This limits results to a preset timeframe. This is a relative time range and results will vary based on when the query is run.

Options: LAST_30D, LAST_WEEK, TODAY, YESTERDAY.

Note: To define the level of data aggregation, include timeIncrement, which can take values DAILY, HOURLY, MONTHLY. timeIncrement is an optional parameter and defaults to ALL

query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timePreset:LAST_30D, timeIncrement: DAILY) {
      reports {
        impressions
      }
    }
  }
}

Filter by an Absolute Time Range

This limits results to the absolute time range specified.

The maximum range is 3 months and the earliest date supported is 2 years in the past.

Note: To define the level of data aggregation, include timeIncrement, which can take values DAILY, HOURLY, MONTHLY. timeIncrement is an optional parameter and defaults to ALL

query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-17T00:00:00Z"}, timeIncrement: DAILY) {
      reports {
        impressions
      }
    }
  }
}