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

Last updated 5 hours 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

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

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

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Unity Offerwall

Offerwall Android SDK

Offerwall iOS SDK

Offerwall Unity SDK

Unity Offerwall

Reporting API for advertisers

Prerequisites

Advertiser reporting metrics

Advertiser metric

Description

Calculation

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