Reporting API - Advertiser
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 minutesLast updated 3 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, 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 that CTCT metrics are only reported in the 1st UTC hour of every day. When using a granularity of
|
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
|
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 (i.e. user has not scrolled far enough to see the ad). We recommend Advertisers to use
|
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
|
dayXRoasAdRevenue | Total ad revenue generated by an offer
|
dayXRoasEngagements | Total user engagements
|
dayXRoasIapRevenue | Total IAP revenue generated by an offer
|
dayXRoasRevenue | Total revenue (IAP + Ad Revenue) generated by an offer
|
dayXRoasSpend | Total advertiser spend
|
spend | Total amount spent |
totalRevenue | Total revenue (IAP + Ad Revenue) generated by an offer during the selected time range. This is calculated as
|
- 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
{
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
{
advertiser{
id
campaigns(first: 2){
nodes{
insights{
reports{
impressions
platform
}
}
}
}
}
}
Segment 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/Campaign
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
{
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 adSetquery { 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 Setsquery { advertiser { adSets(first: 2) { edges { node { insights(timePreset:TODAY) { reports { conversions } } } } } } }
Filter by Publisher App
This limits results to the specified publisher app IDsquery { 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
PAUSED
query { advertiser { adSets(first: 2, configuredStatus: ACTIVE) { edges { node { insights(timePreset:TODAY) { reports { conversions } } } } } } }
Filter by Country
This limits results to the specified countriesquery { 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
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.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