Documentation

Support

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.

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

amountBid for this event
averageBidTotal Spend divided by Total Conversions
callToActionClicksThe 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.
conversionsNumber of conversions for the ad objective
csConversionsNumber of Customer Service conversions for the ad objective
csSpendTotal Customer Support amount spent
ecpiTotal Spend divided by Total Engagements
engagementInstallsThe number of installs inferred from engagements
iaaRevenueTotal Ad Revenue generated by an offer during the selected time range
iapRevenueTotal 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.
offerwallAverageRankThe (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
below.
offerwallTrueImpressionsThe number of times the ad was viewed by a user in the offerwall. Each view registers as a true impression.
returnOnAdSpendReturn 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
.
spendTotal 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 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 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
.
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