Reporting API for publishers

Access Tapjoy Offerwall's Reporting API as a publisher to retrieve detailed data, monitor and assess app performance, and optimize your monetization strategies.

Read time 5 minutes

Last updated 2 months ago

As a Publisher, you can use the Reporting API to retrieve reporting data for your apps that serve the Offerwall.

Prerequisites

You must authenticate with the API. Refer to API authentication.

For information on how to manage your content through the Reporting API, refer to Content Management.
For information on error handling and limitations with the Reporting API, refer to Reporting API Best Practices.

Publisher reporting metrics

The Reporting API can be used to request performance data for your Offerwall content, including metrics such as clicks, conversions, and total revenue. All available publisher reporting metrics are listed in the chart below. We recommend publishers to start with the following base query to retrieve performance metrics:


{  publisher {    placements(appId: "00000000-0000-0000-0000-000000000000") {      id      name      insights(        timeRange: {from: "YYYY-MM-DDT00:00:00Z", until: "YYYY-MM-DDT00:00:00Z"}      ) {        timestamps        reports {          dailyUniqueViewers          earnings        }      }    }  }}

Publisher Metric	Description	Country	App Group	Single Publisher App	Placement	Sum across all Publisher Apps
`averageDuc`	Average number of unique users that converted on an offerwall ad in the app, placement, or content card (counted once per 24 hours per user) divided by number of days	yes	yes	yes	yes	yes
`arpdau`	Average revenue per daily active user (total revenue divided by the number of daily active users)	yes	yes	yes	no	yes
`arpduv`	Average revenue per daily unique offerwall viewer (total revenue divided by the number of unique users that viewed an offerwall in the app (counted once per 24 hours per user)	yes	yes	yes	no	yes
`averageDau`	Average number of daily active users (counted once per 24 hours per user) divided by number of days	yes	yes	yes	no	yes
`averageDuv`	Average number of unique users that viewed an offerwall in the app (counted once per 24 hours per user) divided by number of days	yes	yes	yes	no	yes
`clicks`	Number of clicks that originated from the placement	yes	no	no	yes	no
`conversions`	Number of conversions that originated from the placement	yes	no	no	yes	no
`dailyActiveUsers`	Number of daily active users	yes	yes	yes	no	yes
`dailyUniqueConversions`	Number of users who converted on an ad from this placement or content card (counted once per 24 hours per user). Currently only applies to offerwall content cards	yes	no	no	yes	no
`dailyUniqueOfferwallEngagements`	Number of unique users that converted on an offerwall ad in the app (counted once per 24 hours per user)	yes	yes	yes	no	yes
`dailyUniqueOfferwallViewers`	Number of unique users that viewed an offerwall in the app (counted once per 24 hours per user)	yes	yes	yes	no	yes
`dailyUniqueViewers`	Number of unique users who viewed an ad in this placement or content card (counted once per 24 hours per user). Currently only applies to offerwall content cards	yes	no	no	yes	no
`ducduv`	Number of users who converted on an ad from this placement or content card (counted once per 24 hours per user) divided by the number of users who viewed an ad in this placement or content card (counted once per 24 hours per user)	yes	yes	yes	yes	yes
`duvDau`	Number of unique users that viewed an offerwall in the app (counted once per 24 hours per user) divided by the number of daily active users	yes	yes	yes	no	yes
`earnings`	Total amount earned	yes	no	no	yes	no
`eCPM`	Total revenue / (Total Offerwall Opens / 1000). This is represented in USD	yes	no	no	yes	no
`impressions`	Number of impressions that originated from the placement	yes	no	no	yes	no
`newUsers`	Number of new users	yes	yes	yes	no	yes
`offerwallViews`	Total number of offerwall open	yes	yes	yes	no	yes
`sessions`	Number of app opens	yes	yes	yes	no	yes
`totalRevenue`	Total revenue	yes	yes	yes	no	yes

Additional publisher metrics available in the Dashboard:

Impressions/Views
Conversion Rate (CVR)

Metric segmentations

By adding segment fields to your queries, the API can return performance data broken down by app, placement, and/or country. The Reporting API supports segmentation under the following breakdowns:

country
id (App Group ID)
id (Publisher App ID)
placement
platform
total across all Publisher Apps

Segmentation examples

Segment by country

The following query returns daily unique viewer data for a specific placement, segmented by country.


{  publisher {    placements(appId: "00000000-0000-0000-0000-000000000000") {      id      insights(timePreset: TODAY) {        timestamps        reports {          country          dailyUniqueViewers        }      }    }  }}


{  "data": {    "publisher": {      "placements": [        {          "id": "00000000-0000-0000-0000-000000000001",          "insights": {            "timestamps": [              "2024-11-15T00:00:00Z"            ],            "reports": [              {                "country": "AU",                "dailyUniqueViewers": [                  115                ]              },              {                "country": "IR",                "dailyUniqueViewers": [                  18                ]              },              {                "country": "ZA",                "dailyUniqueViewers": [                  2                ]              }            ]          }        }      ]    }  }}

Segment by app group

The following query returns daily active user data for the first three apps, segmented by app group ID.


{  publisher {    apps(first: 3) {      nodes {        appGroupId        insights(timePreset: TODAY) {          reports {            dailyActiveUsers          }        }      }    }  }}


{  "data": {    "publisher": {      "apps": {        "nodes": [          {            "appGroupId": "00000000-0000-0000-0000-000000000000",            "insights": {              "reports": [                {                  "dailyActiveUsers": [                    12                  ]                }              ]            }          },          {            "appGroupId": "00000000-0000-0000-0000-000000000001",            "insights": {              "reports": [                {                  "dailyActiveUsers": [                    31                  ]                }              ]            }          },          {            "appGroupId": "00000000-0000-0000-0000-000000000002",            "insights": {              "reports": [                {                  "dailyActiveUsers": [                    3                  ]                }              ]            }          }        ]      }    }  }}

Segment by publisher app

The following query returns daily active user data for the first three publisher apps, segmented by app name.


query {  publisher {  apps(first:3) {      edges {        node {          name          insights(timePreset:TODAY) {            reports {              dailyActiveUsers            }          }        }      }    }  }}


{  "data": {    "publisher": {      "apps": {        "edges": [          {            "node": {              "name": "example_app1",              "insights": {                "reports": [                  {                    "dailyActiveUsers": [                      78                    ]                  }                ]              }            }          },          {            "node": {              "name": "example_app2",              "insights": {                "reports": [                  {                    "dailyActiveUsers": [                      12                    ]                  }                ]              }            }          },          {            "node": {              "name": "example_app3",              "insights": {                "reports": [                  {                    "dailyActiveUsers": [                      15                    ]                  }                ]              }            }          }        ]      }    }  }}

Segment by placement

The following query returns impression data for all placements in a specific app, segmented by placement.


{  publisher{    placements(appId: "00000000-0000-0000-0000-000000000000") {      id      name      insights(timePreset: TODAY) {        reports {          impressions        }        timestamps      }    }  }}


{  "data": {    "publisher": {      "placements": [        {          "id": "00000000-0000-0000-0000-000000000000",          "name": "AppLaunch",          "insights": {            "reports": [              {                "impressions": [                  0                ]              }            ],            "timestamps": [              "2024-11-15T00:00:00Z"            ]          }        },        {          "id": "00000000-0000-0000-0000-000000000000",          "name": "offerwall",          "insights": {            "reports": [              {                "impressions": [                  2590                ]              }            ],            "timestamps": [              "2024-11-15T00:00:00Z"            ]          }        }      ]    }  }}

Segment by platform

The following query returns daily unique viewer data for a specific placement, segmented by platform.


  publisher {    placements(appId: "00000000-0000-0000-0000-000000000000") {      id      insights(timePreset: TODAY) {        timestamps        reports {          platform          dailyUniqueViewers        }      }    }  }}


{  "data": {    "publisher": {      "placements": [        {          "id": "00000000-0000-0000-0000-000000000001",          "insights": {            "timestamps": [              "2024-11-15T00:00:00Z"            ],            "reports": [              {                "platform": "ios",                "dailyUniqueViewers": [                  78                ]              }            ]          }        }      ]    }  }}

Sum across all publisher apps

This represents the total or sum of the requested metrics, across all apps under this Publisher. The following query returns eCPM, total revenue, and offerwall views summed across all publisher apps for today.


{  publisher {    publisherAppInsights(timePreset: TODAY) {      timestamps      reports {        ecpm        totalRevenue        offerwallViews      }    }  }}


{  "data": {    "publisher": {      "publisherAppInsights": {        "timestamps": [          "2025-08-27T00:00:00Z"        ],        "reports": [          {            "ecpm": [              4.108913673386            ],            "totalRevenue": [              57149851536            ],            "offerwallViews": [              461224            ],          }        ]      }    }  }}

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:

appId (single app)
apps (the first or last x apps)
appGroupId
content
country
platform
timePreset
timeRange

Filtering examples

Filter by app

This limits results to a single App


{  publisher{    app(id: "<app ID>") {      id      name      insights(timePreset: TODAY) {        reports {          arpdau        }        timestamps      }    }  }}

Filter for multiple apps

This limits results to the first or last x Apps


{  publisher {    apps(first: 3) {      nodes {        id        platform        insights {          reports {            arpdau            totalRevenue          }        }      }    }  }}

Filter by app group ID

This limits results to apps under a specific App Group ID


{  publisher {    publisherAppInsights(timePreset: TODAY, filter: {appGroupIds: ["00000000-0000-0000-0000-000000000000"]}) {      timestamps      reports {        offerwallViews        eCPM        totalRevenue      }    }

Filter by content card

This limits results to a single Content Card ID


{  publisher {    placements(appId: "<app ID>") {      id      name      content(id: "<content ID>") {        id        type        insights(timePreset: TODAY) {        timestamps          reports {            earnings          }        }      }    }  }}

Filter by country

This limits results to the specified geos


{  publisher {    publisherAppInsights(timePreset: TODAY, filter: {countries: ["KR, US"]}) {      timestamps      reports {        offerwallViews        eCPM        totalRevenue      }    }

Filter by platform

This limits results to the specified platforms


{  publisher {    publisherAppInsights(timePreset: TODAY, filter: {platforms: [ios]}) {      timestamps      reports {        offerwallViews        eCPM        totalRevenue      }    }

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


{  publisher {    placements(appId: "<app ID>") {      content(id: "<content card ID>") {        insights(timePreset:LAST_30D, timeIncrement: DAILY) {        timestamps          reports {            dailyUniqueViewers          }        }      }    }  }}

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


{  publisher {    placements(appId: "<app ID>") {      content(id: "<content card ID>") {        insights(timeRange: {from: "2024-11-15T00:00:00Z", until: "2024-11-17T00:00:00Z"}, timeIncrement: DAILY) {        timestamps          reports {            dailyUniqueViewers          }        }      }    }  }}

Deprecated dimensions

The following legacy dimensions will 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. Objects > ContentCard > ecpmSettings Enums > PublisherContentType:

```
ANNOUNCEMENT
```
```
DIRECT_PLAY_HOUSE_AD
```
```
FEATURED
```
```
FSI_HOUSE_AD
```
```
IAP_PROMOTION
```
```
INTERSTITIAL_VIDEO
```
```
MEDIATED_DIRECT_PLAY
```
```
MEDIATED_FSI
```
```
PREVIEW_CODE
```
```
PROGRAMMATIC_INTERSTITIAL_VIDEO
```
```
PROGRAMMATIC_REWARDED_VIDEO
```
```
REWARDED_VIDEO
```
```
TJ_RECOMMENDED
```
```
REWARD_UNLOCK
```

Input Objects >

CreatePlacementAndContentSetInput

> ecpmSettingsToAdd Input Objects >

UpdatePlacementAndContentSetInput

```
ecpmSettingsToAdd
```
```
ecpmSettingsToDelete
```
```
ecpmSettingsToUpdate
```