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

Last updated 2 months 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

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 that 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.
iaaRevenue	Total Ad Revenue generated by an offer during the selected time range.
iapRevenue	Total IAP Revenue generated by an offer during the selected time range.
impressions	The number of times the ad was clicked on in the offerwall. Note that 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 that 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). 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 that 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 `dayXRoasRevenue` divided by `dayXRoasSpend` . If `dayXRoasRevenue` 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 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. This is calculated as `dayXRoasIapRevenue` plus `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.
totalRevenue	Total revenue (IAP + Ad Revenue) generated by an offer during the selected time range. This is calculated as `iaaRevenue` plus `iapRevenue` .

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

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 legacy dimensions were be removed from the Reporting API on February 3, 2025. Ensure that your API queries do not reference any of the dimensions listed in bold below to prevent errors when fetching data from Tapjoy's Offerwall.

Enums > TargetConnectionType > MOBILE
Enums > TargetDeviceType > WINDOWS

Documentation

Development

User Acquisition

Monetization

Industry