Documentation

​
​

Development

User Acquisition

Monetization

Industry

Unity Offerwall

Offerwall Android SDK

Offerwall iOS SDK

Offerwall Unity SDK

Unity Offerwall

Tapjoy Offerwall
​
​
Dashboard
  • CPE campaigns
  • Deferred deeplinks
  • Payment security
ROAS optimization
  • ROAS optimization
  • Introduction to ROAS optimization
  • Get started with ROAS optimization
  • Target ROAS optimizer best practices
APIs
  • API authentication
  • Reporting API advertiser
  • Reporting API best practices
  • Campaign management
  • Audience API overview
MMP integrations
  • MMP integrations
  • Adjust
  • Appsflyer
  • Singular
  1. Grow your game
  3. Unity Offerwall
  5. Offerwall user acquisition

Reporting API for advertisers

Access Tapjoy Offerwall's Reporting API as an advertiser to retrieve detailed data, monitor and assess app performance, and optimize your reporting queries for better campaign insights.
Read time 13 minutes
Last updated 24 days ago
As an Advertiser, you can use the Reporting API to retrieve reporting data for your ads that are served in the Offerwall.

Prerequisites

You must authenticate with the API.
  • For information on how to manage your campaigns through the Reporting API, refer to Campaign Management.
  • For information on error handling and limitations with the Reporting API, refer to Reporting API Best Practices.

Advertiser reporting metrics

Use the Reporting API to request performance data for your ad sets and multi-reward events, including metrics such as revenue, impressions, and conversions.
The recommended best practice is 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      }    }  }}
Refer to the following table for a list of advertiser reporting metrics:

Advertiser metric

Description

Calculation

amount
The advertiser-configured bid for this event.Not applicable
averageBid
The average bid amount.
Note
This is a derived metric representing the realized average bid paid per conversion, not the configured bid (
amount
).
Total Spend ÷ Total Conversions.
callToActionClicks
The number of times users clicked the call-to-action, if a call-to-action is present.Not applicable
clickToConversionTime
Click to conversion time data segmented in several different ways.
Note
CTCT metrics are only reported in the first UTC hour of every day. When you use a granularity of 
HOURLY
, only the hour representing 
00:00:00 UTC to 00:59:59 UTC
will have a value other than 0.
Not applicable
conversions
Number of conversions for the ad objective.Not applicable
csConversions
Number of Customer Service conversions for the ad objective.Not applicable
csSpend
Total Customer Support amount spent.Not applicable
ecpi
Effective cost per engagement.Total Spend ÷ Total Engagements.
engagementInstalls
The number of installs inferred from engagements.Not applicable
iaaRevenue
Total Ad Revenue generated by an offer during the selected time range.Not applicable
iapRevenue
Total IAP Revenue generated by an offer during the selected time range.Not applicable
impressions
The number of times the ad was clicked on in the offerwall.
Note
This metric more accurately represents 
clicks
, not 
impressions
.
Not applicable
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 (for example, user has not scrolled far enough to see the ad). The recommended best practice is to use 
offerwallTrueImpressions
.
Not applicable
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 (ROAS) data for users who installed on each day.
Note
ROAS metrics are only reported in the first UTC hour of every day.
Not applicable
dayXRoas
Total return on ad spend 
X
days from install.
dayXRoasRevenue
÷ 
dayXRoasSpend
Available for 
X
= 
0
, 
1
, 
2
, 
3
, 
4
, 
5
, 
6
, 
7
, 
14
, 
30
, 
60
, 
90
Note
If 
dayXRoasRevenue
is 0, this field will also be 0.
dayXRoasAdRevenue
Total ad revenue generated by an offer 
X
days after install, from users who installed the offer during the selected time range.
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 IAP revenue generated by an offer 
X
days after install, from users who installed the offer during the selected time range.
Available for 
X
= 
0
, 
1
, 
2
, 
3
, 
4
, 
5
, 
6
, 
7
, 
14
, 
30
, 
60
, 
90
dayXRoasRevenue
Total revenue (IAP + Ad Revenue) generated by an offer 
X
days after install, from users who installed the offer during the selected time range.
dayXRoasIapRevenue
+ 
dayXRoasAdRevenue
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.Not applicable
totalRevenue
Total revenue (IAP + Ad Revenue) generated by an offer during the selected time range.
iaaRevenue + iapRevenue
.
Note
When segmented by 
multiRewardEngagementEvent
, 
averageBid
represents the realized average bid paid per conversion for each engagement event over the selected range, not the configured bid. For the configured bid, refer to 
amount
in Campaign management.
averageBid
is returned as an array with one value per time bucket, like other insights metrics, with a single element when 
timeIncrement
is 
ALL
. A value of 
null
means there were no conversions for that event in the bucket.
The following additional advertiser metrics are also 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 segements such as event, publisher app, or country. 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

The following query returns conversion data segmented by country, attribution source, and language for a specific ad set and time range.
{ 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

The following query returns impression data for the first two campaigns, segmented by platform.
{ advertiser{ id campaigns(first: 2){ nodes{ insights{ reports{ impressions platform } } } } }}

Segment by publisher app

The following query returns impressions, conversions, and spend for a specific ad set, broken down by publisher app.
query { adSet(id: "00000000-0000-0000-0000-000000000000") { ads { id insights(timePreset: TODAY) { reports { app { bundleId } impressions conversions spend } } } }}

Segment by ad set or campaign

The following query returns conversions and spend for up to 50 active ad sets over a specified time range.
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

The following query returns conversions and day-0 ROAS for a specific ad set, segmented by multi-reward engagement event.
{ 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 } } } }}

Retrieve average bid per engagement event

To see the realized average bid for each engagement event of a multi-reward (MR-CPE) ad set over a time range, request the 
averageBid
metric while segmenting by 
multiRewardEngagementEvent
. Use 
timeIncrement: ALL
to get a single average per event across the whole range.
query EventAverageBids($adSetId: ID!) { adSet(id: $adSetId) { insights( timeRange: { from: "2024-03-01T00:00:00Z", until: "2024-03-08T00:00:00Z" } timeIncrement: ALL ) { reports { multiRewardEngagementEvent { displayName eventName eventValue } averageBid } } }}
To pull this across every ad set for your account, traverse 
advertiser { campaigns(first: 100) { nodes { adSetsWithoutPagination { id name insights(...) { ... } } } } }
.

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

Deprecated dimensions

The following deprecated dimensions are unavailable as of February 2025. Ensure that your API queries don't reference any of the following dimensions to prevent errors when fetching data from Tapjoy's Offerwall:
  • Enums > TargetConnectionType > MOBILE
  • Enums > TargetDeviceType > WINDOWS
Copyright © 2026 Unity Technologies
LegalPrivacy PolicyCookiesDocumentation Terms of UseDo Not Sell or Share My Personal InformationYour Privacy Choices (Cookie Settings)

"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S and elsewhere (more info here). Other names or brands are trademarks of their respective owners.

Some pages are machine-translated for convenience, and may contain inaccuracies. In the event of conflicting information, the English version is authoritative.

  • On this page

    • Prerequisites

    • Advertiser reporting metrics

    • Metric segmentations

      • Segmentation examples

        • Segment by country, attribution source, and/or language

        • Segment by platform

        • Segment by publisher app

        • Segment by ad set or campaign

        • Segment by multi-reward engagement event

        • Retrieve average bid per engagement event

    • Filtering capabilities

      • Filtering examples

        • Filter by ad set

        • Filter for multiple ad sets

        • Filter by publisher app

        • Filter by configured status

        • Filter by country

        • Filter by a preset timeframe

        • Filter by an absolute time range

    • Deprecated dimensions

Report a problem with this page