Contents

Reporting API

The Integral Ad Science (IAS) Reporting Application Programming Interface (Reporting API) is a RESTful API that exposes IAS viewability, fraud, and brand safety metrics.

API Overview

The Integral Ad Science (IAS) Reporting Application Programming Interface (Reporting API) is a RESTful API that exposes IAS viewability, fraud, and brand safety metrics. It allows you to leverage IAS's data for your own internal business applications organized by "dimensions" of your choice such as specific campaigns and publishers. You can access all endpoints with the HTTP GET method. In the report creation, you can specify various dimensions to group the data (for example, Campaigns, Device, DSP, etc.).

Note: Macro level dimensions are only available for impressions running on eligible DSPs.

The Reporting API returns data as configured in the tag before it is trafficked; if you suspect missing data, your IAS technical support representative will provide a sample query to ensure your tags are properly configured. IAS only shows data for the requested team ID.

Authentication

The Reporting API uses OAuth 2.0 with the 'password' grant flow. The 'username' is the IAS Signal username, and 'password' is the password for the IAS Signal username. Coordinate with your IAS representative to obtain a client ID and client secret. Once generated, you can re-use the token with multiple requests to the reporting API until the token expires (which is indicated with the error 'invalid_token' and an error description 'Access token expired').

The token to use for requests is the value from the "access_token" key in the JSON response.

curl -u <Client ID>:<Client Secret> https://data.integralplatform.com/auth/uaa/oauth/token -d 'username=<putyourusernamehere>&password=<putyourpasswordhere>&grant_type=password'

Base URL Templates

Area

URL

Authentication Token URL

https://data.integralplatform.com/auth/uaa/oauth/token

Base Endpoint

https://data.integralplatform.com

APIs

Creates a report using a JSON file as input. The Create Report API is ASYNC so use Check Status to learn when the report is ready.

You can create reports with the the following types of report types:

  • Performance Report Input File - uses IAS-measured data and metrics to evaluate your campaigns.

  • Brand Suitability Failure Report Input File - for participating advertisers, this report uses IAS data to evaluate brand safety reasons on why an ad wasn't displayed.

  • Facebook Reporting Input File - uses IAS data to gain insights into Facebook performance.

  • YouTube Reporting Input File - uses IAS data to gain insights into YouTube performance.

  • YouTube Contextual Suitability Reporting Input File - uses IAS data to gain aggregate level insights into YouTube Contextual Suitability performance.

  • YouTube Content Level Contextual Suitability Reporting Input File - uses IAS data to gain content level insights into YouTube Contextual Suitability performance.

  • Collision Reporting Input File - uses IAS data to gain insight into ad collisions.

  • Geo Compliance Reporting Input File - uses IAS data to gain insights into Geo Compliance.

  • GroupM Fully On Screen Reporting Input File - uses IAS data to gain insights on GroupM Fully On Screen metrics.

  • Domain Mismatch Reporting Input File - uses IAS data for insights on discrepancies between the Bid Domain (the domain the DSP reported) and Measured Domain (the domain IAS detected).

  • TikTok Input File - uses IAS data for Brand Safety and Video-Level insights.

  • Total Visibility Input File - uses IAS data for insights into the supply path and costs.

  • Attention Reporting Input File - uses IAS data for insights into attention.

A report defines the teams you want data from, the time period to get data, and the metrics to collect. Additionally, you can group the metrics according to various dimensions. For example, you can view Measured Ads per URL using the Domains dimension.

The IAS Help Center contains more information about metrics and any metric minimum thresholds.

See 'Inputs' for an example of the input file and each report's 'Input File' section for a detailed explanation of the report properties. Additionally, Sample Reports includes numerous examples of reports using various dimensions.

Curl

curl -vX --location --request POST 'https://data.integralplatform.com/report' --header "Authorization: Bearer ${TOKEN}" --header 'Content-Type: application/json' -d "@{jsonFile}"

Input

Name

In

Type

Required

Description

jsonFile

body

ReportRequest

true

JSON input file to upload. The JSON file defines the report's settings.

The JSON input file defines the following properties:

  • reportName

  • reportTeamIds

  • reportStart

  • reportEnd

  • reportType

  • fileType

  • metrics Performance, Brand Suitability, Facebook, YouTube, and Collision

  • parameters

  • ultimateAdvertiserIds

  • customMetrics

  • dimensions

  • dimensionFilters

  • thresholdCondition

See the Performance, Brand Suitability Failure, Facebook, YouTube, or Collision Report Type for property descriptions, required settings, and possible values for each report type.

Example JSON Input File:

{
"reportName": "Reporting_API_Example",
"reportTeamIds": [ 12345 ],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "IAS_PERFORMANCE",
"fileType": "CSV",
"metrics": [
"Invalid Traffic",
"Not Viewable Ads"
],
"dimensions": [
"Campaigns",
"Teams"
]
}

Outputs

Name

Type

Notes

id

integer(int64)

This ID value is used to

check on status

and to

download

the report.

status

string

SUBMITTED, PENDING, NO_RESULTS, ERROR, READY

Create Report Example Output:

{
"id": 25,
"status": "SUBMITTED"
}

Performance Report Type

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Reporting_API_ Example_Performance"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-16"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

IAS_PERFORMANCE

For example: "reportType": "IAS_PERFORMANCE"

Metrics Performance

The metrics which you want in your report.

Performance example metrics:

"metrics": [
"Total tracked ads"
]

For a Performance Report, the following metrics are available grouped in these categories:

  • Summary

  • Viewability

  • Viewability Rendered

  • Viewability Gross Net

  • Viewability Gross Net Impressions

  • Viewability Distribution

  • Failure Reasons

  • Quality Impressions

  • Brand Safety

  • Risk Categories

  • Invalid Traffic

  • Invalid Traffic By Type

  • Video Quartiles

  • Carbon Emissions

  • Site Quality

  • Video

Summary

  • Blocking status

  • Total tracked ads

  • Tracked ads share rate

Viewability

  • Average Time-in-View

  • Time-in-View Distribution

  • Eligible Ads for Viewability Measurement

  • Measured ads

  • Measured Rate (out of Ads)

  • Unmeasured ads

  • Unmeasured rate

  • Viewable impressions

  • Viewable rate (out of measured ads)

  • Not viewable ads

  • Not viewable rate (out of measured ads)

Viewability Rendered

  • Total rendered impressions

  • Eligible impressions for viewability

  • Net impressions

  • Total net impressions

  • Measured impressions

  • Unmeasured impressions

  • Viewable rate (out of measured impressions)

  • Not viewable impressions

  • Not viewable rate (out of measured impressions)

  • Measured Rate (out of eligible impressions)

  • Net Measured Rate (out of eligible impressions)

Viewability Gross Net

  • Gross eligible ads

  • Gross measured ads

  • Gross Measured Rate (Out of Gross Eligible Ads)

  • Gross unmeasured ads

  • Gross Unmeasured Rate (Out of Gross Eligible Ads)

  • Net eligible ads for viewability measurement

  • Net measured ads

  • Net Measured Rate (out of net eligible ads)

  • Net unmeasured ads

  • Net Unmeasured Rate (out of net eligible ads)

  • Net viewable ads

  • Net Viewable Rate (Out of Net Measured Ads)

  • Net not viewable ads

  • Net Not Viewable Rate (Out of Net Measured Ads)

Viewability Gross Net Impressions

  • Gross eligible impressions

  • Gross measured impressions

  • Gross Measured Rate (Out of Gross Eligible Impressions)

  • Gross unmeasured impressions

  • Gross Unmeasured Rate (Out of Gross Eligible Impressions)

  • Net eligible impressions for viewability measurement

  • Net measured impressions

  • Net Measured Rate (out of net eligible impressions)

  • Net unmeasured impressions

  • Net Unmeasured Rate (out of net eligible impressions)

  • Net viewable impressions

  • Net Viewable Rate (Out of Net Measured Impressions)

  • Net not viewable impressions

  • Net Not Viewable Rate (Out of Net Measured Impressions)

Viewability Distribution

  • Ad distribution: viewable rate

  • Ad distribution: not viewable rate

  • Ad distribution: measured rate

  • Ad distribution: unmeasured rate

  • Ad distribution: net measured rate

  • Ad distribution: net unmeasured rate

  • Ad distribution: net viewable rate

  • Ad distribution: net not viewable rate

  • Impression distribution: unmeasured rate

  • Impression distribution: viewable rate

  • Impression distribution: not viewable rate

  • Impression distribution: net unmeasured rate

  • Impression distribution: net viewable rate

  • Impression distribution: net not viewable rate

Failure Reasons

  • Brand safety risk ads

  • Brand safety risk rate

  • Brand suitability failed ads

  • Brand suitability fail rate

  • Custom keyword exclusion list ads

  • Custom keyword exclusion list rate

  • Custom URL/App exclusion List ads

  • Custom URL/App exclusion List rate

  • Out of geo ads

  • Out of geo rate

  • Invalid traffic ads

  • Invalid traffic rate

  • Invisible URL ads

  • Invisible URL rate

  • Target language mismatch ads

  • Target language mismatch rate

Quality Impressions

Quality Impressions are ads which meet custom criteria set by your team across Viewability, Invalid Traffic (IVT), Brand Safety, and Geo Targeting. You can create a report which disables the Viewability and, or Geo Targeting criteria using the Parameters option.

If you are using any of the Quality Impressions metrics, you must include 'Total tracked ads' as a metric. See Sample Reports for an example Quality Impressions Report. The Quality Impressions metrics:

  • Eligible ads for quality impressions

  • Eligible rate for quality impressions

  • Quality impressions

  • Quality impressions rate

  • Non-quality ads

  • Non-quality rate

  • Non-quality blocked ads

  • Non-Quality Not Viewable Ads

  • % Non quality: not viewable

  • Failed brand safety ads

  • % Non quality: failed brand safety

  • Non-Quality Invalid Traffic Ads

  • % Non quality: IVT

  • Non-Quality Out of Geo Ads

  • % Non quality: Out of geo

Brand Safety

  • Total eligible ads for brand safety

  • Passed ads

  • Pass rate

  • Failed ads

  • Fail rate

  • Blocked ads

  • Block rate (% of failed)

  • See-through ads

  • See-through rate

Risk Categories

  • Adult Ads

  • % Adult Ads

  • Alcohol Ads

  • % Alcohol Ads

  • Hate Speech Ads

  • % Hate Speech Ads

  • Illegal Downloads Ads

  • % Illegal Downloads Ads

  • Drugs Ads

  • % Drugs Ads

  • Offensive Language Ads

  • % Offensive Language Ads

  • Violence Ads

  • % Violence Ads

Invalid Traffic

  • Eligible ads for invalid traffic detection

  • Eligible rate for invalid traffic detection

  • Invalid traffic

  • Invalid traffic rate

  • Valid traffic

  • Valid traffic rate

  • Blocked invalid traffic

  • % of invalid traffic blocked

  • Unblocked invalid traffic

  • % of invalid traffic unblocked

Invalid Traffic By Type

  • General invalid traffic (GIVT) ads

  • General invalid traffic (GIVT) rate

  • Sophisticated invalid traffic ads

  • Sophisticated invalid traffic rate

  • Bots (SIVT) ads

  • Bots (SIVT) rate

  • Domain spoofing (SIVT) ads

  • Domain spoofing (SIVT) rate

  • Hidden ads (SIVT) ads

  • Hidden ads (SIVT) rate

  • Reduced value inventory ads

  • Reduced value inventory rate

  • Incentivized browsing (RVI) ads

  • Incentivized browsing (RVI) rate

  • Proxy servers (RVI) ads

  • Proxy servers (RVI) rate

Video Quartiles

  • Valid video ads

  • Valid Viewable Video Impressions

Carbon Emissions

  • Good-Loop CO2 (eKg)

  • Good-Loop tracked ads

  • Scope3 CO2 (eKg)

  • Scope3 tracked ads

Site Quality

  • MFA Ads

  • MFA Rate

  • Ad Clutter Ads

  • Ad Clutter Rate

Video

  • Pause/Unpause

  • User Scroll

  • Volume Up/Down/Mute

  • Full-Screen Plays

  • Auto play ads

  • Click to play ads

  • Unknown player state ads

  • Valid quartiles

  • Valid quartiles rate (% of Valid Video Ads)

  • Viewable valid quartiles

Viewable Valid Quartiles Rate (% of Valid Viewable Video Impressions)

Parameters

The boolean parameters 'Quality Criteria Geo' and 'Quality Criteria Viewability' are available only for Quality Impressions metrics (these parameters are not applicable for non Quality Impressions metrics). These parameters allow you to disable the custom criteria your teams set for the Quality Impressions for Geo targeting and, or Viewability.

When you set the parameter 'Quality Criteria Geo' to false, then you no longer can use the Quality Impressions metrics 'Non-Quality Out of Geo Ads' and '% Non quality: Out of geo'; if you set 'Quality Criteria Geo' to false and use the 'Non-Quality Out of Geo Ads' and, or '% Non quality: Out of geo' metrics, the report returns bad data for those metrics.

When you set the parameter 'Quality Criteria Viewability' to false, then you no longer can use the Quality Impressions metrics 'Non-Quality Not Viewable Ads' and '% Non quality: not viewable'; if you set 'Quality Criteria Viewability' to false and use the 'Non-Quality Not Viewable Ads' and, or '% Non quality: not viewable', the report returns bad data for those metrics.

Example Setting Parameters:

"metrics": [
"Total tracked ads",
"Quality impressions",
"Quality impressions rate",
"Non-Quality Out of Geo Ads",
"% Non quality: Out of geo"
],
"parameters" : {
"Quality Criteria Geo" : true ,
"Quality Criteria Viewability" : false
}

Ultimate Advertiser IDs

'ultimateAdvertiserIds' is used in conjunction with the 'Advertiser' dimension, this setting allows you to get data for many teams with a single advertiser ID. Contact your IAS representative for the ultimate advertiser IDs.

Example:

"metrics": [
"Total tracked ads"
],
"dimensions": [
"Advertiser"
],
"ultimateAdvertiserIds":[1,6]

Custom Metrics

You need to declare the 'id' and the 'name'. Custom Metrics are only available for a Performance Report or Total Visibility Report.

Contact your IAS representative for the name and ID for the custom metrics.

Example:

"customMetrics": {
"id":"123",
"name":"name123"
}

Dimensions and Dimension Filters

Dimensions and dimension filters groups and limits data according to what your settings. The 'dimensionFilter' field is the dimension name, except for 'Date' which uses 'dateBreakout' to set the time span.

Sending the wrong dimensions or metrics to a report type that doesn't support them causes report creation to fail. For example, you can't use Teams, App, or Domains in the same report, and all the DSP dimensions are not compatible with the Apps dimension. See the Sample Dimensions and Dimension Filters or Sample Reports for examples of creating reports for various dimensions.

If you don't set a specific dimension filter, all the values are shown for that dimension.

Macro level dimensions are only available for impressions running on eligible DSPs.


Dimension

Possible Values

Advertiser

Allows you to get data for multiple teams at once. Use in conjunction with the 'ultimateAdvertiserIds' property.

Apps

If you use the 'Apps' dimension, then you can't also use the DSP dimensions.

Campaigns

active

or specific campaigns.

Channel (Exchange)

If you use the 'Channel (Exchange)' dimension, you can't also group by the 'Apps' dimension.

Contextual Segment

Groups data by Context Control Targeting segments. When you use 'Contextual Segment', you can only use the dimensions:

Campaign

Media partner

DSP

DSP Campaign

Segment

Team

Additionally, you can only use the following metrics:

Eligible Ads for Viewable Measurement

Measured Ads

Measured Rate (out of Ads)

Unmeasured Ads

Unmeasured Rate

Viewable Impressions

Viewable Rate

Not Viewable Ads

Not Viewable Rate

Total Tracked Ads

Creatives

The report contains a breakout for creatives.

Date

Use 'dateBreakout' to define the time span. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Device

desktop (1)

smartphone (2)

tablet (3)

connected TV (5)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all devices.

Domains

If you group by the 'Domains' dimension, then you can't also group by the 'Teams' and 'Apps' dimensions.

DSP

DSP Value - DSP Name:

1 - Amobee

2 - Xandr

3 - DV360

8 - MediaMath

9 - TTD

11 - Adobe

12 - AdForm

26 - Zeta Global

28 - Adelphic

30 - VMG

33 - Amazon

58 - Beeswax

If you use the 'DSP' dimension, you can't also group by the 'Apps' dimension.

DSP Campaign

If you use the 'DSP Campaign' dimension, you can't also group by the 'Apps' dimension.

DSP Deal

If you use the 'DSP Deal' dimension, you can't also group by the 'Apps' dimension.

DSP Placement (Line item)

If you use the 'DSP Placement (Line item)' dimension, you can't also group by the 'Apps' dimension.

DSP Publisher

If you use the 'DSP Publisher' dimension, you can't also group by the 'Apps' dimension.

Environment

browser (1)

in-app (2)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all environments.

External Id

External ID.

Format

display (1)

video (2)

If you don't specify 'dimensionFilters', then the API groups by all formats.

Media partners

All or specific media partners. If you don't specify 'dimensionFilters', then the API groups by all media partners.

Placements

All or specific placements. If you don't specify 'dimensionFilters', then the API groups by all placements.

Teams

The team IDs you want to group and, or filter upon.

Dimension and Dimension Filters Template Example:

"dimensions" : [
"<Dimension>"
],
"dimensionFilters" : [
{
"field" : "<Dimension>",
"values" : [
"<Value>"
]
}
]

Date Example:

"dimensions" : [
"Date"
],
"dateBreakout" : "BY_MONTH"

Custom Dimensions

Custom Dimensions are only available for a Performance Report and Unified View customers. Use the custom dimensions in conjunction with the 'ultimateAdvertiserIds' property. Use the Dimension & Values screen in IAS Signal under Campaigns > Unified View Manager to add, delete, or update custom dimensions.

The sample uses "Market" and "Activation Entity" however these dimensions must be configured in IAS Signal to work properly.

Custom Dimensions Example:

"metrics": [
"Total tracked ads"
],
"dimensions": [
"Advertiser"
],
"customDimensions": [
"Market",
"Activation Entity"
],
"ultimateAdvertiserIds": [
2
]

Minimum Filter

You can set a filter to return only data which meets a minimum threshold of total tracked ads, or to include any threshold (-1).

The minimum filter is optional for a Performance Report.

Minimum Filter Example:

"thresholdCondition": {
"metric": "Total tracked ads",
"value": 1000
}

Brand Suitability Failure Report Type

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Reporting_API_ Example_Brand_Suitability"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-16"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

FAILED_BY_BRAND_SUITABILITY_PROFILE

For example: "reportType": "FAILED_BY_BRAND_SUITABILITY_PROFILE"

Metrics Failed By Brand Suitability

Available for participating advertisers, the Brand Suitability Failure Report displays the metric 'Failed ads' to show when an ad didn't appear because the location of the ad failed to match your brand safety settings.

Failed by Brand Suitability Metric Example:

"metrics": [ "Failed ads" ]

Dimensions and Dimension Filters Brand Suitability Failure

See Sample Dimensions and Dimension Filters for additional examples.

Note: you must set 'Segment' as one of the dimensions. However if you use the 'Keyword' dimension, then you can't use 'Segment'.

Dimension

Possible Values

Advertiser

Allows you to get data for multiple teams at once. Use in conjunction with the 'ultimateAdvertiserIds' property.

Campaigns

active

or specific campaigns.

Creatives

The report contains a breakout for creatives.

Date

Use 'dateBreakout' to define the time period. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Device

desktop (1)

smartphone (2)

tablet (3)

connected TV (5)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all devices.

Domains

If you group by the 'Domains' dimension, then you can't also group by the 'Teams' and 'Apps' dimensions.

External Id

External ID.

Format

display (1)

video (2)

If you don't specify 'dimensionFilters', then the API groups by all formats.

Keyword

If you use Keyword, then you can't use the 'Segment' dimension.

Media partners

All or specific media partners. If you don't specify 'dimensionFilters', then the API groups by all media partners.

Page/URL

groups by Page/URL.

Placements

All or specific placements. If you don't specify 'dimensionFilters', then the API groups by all placements.

Segment

Segment is

required

.

Teams

The team IDs you want to group and, or filter upon.

Minimum Filter Brand Suitability Failure

The minimum filter is optional for a Brand Suitability Failure Report.

See Minimum Filter for more information.

Facebook Report Type

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Reporting_API_ Example_Facebook"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-16"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

FACEBOOK_VIEWABILITY

For example: "reportType": "FACEBOOK_VIEWABILITY"

Metrics Facebook

Facebook Example Metrics:

"metrics": [
"# ≥ 2s",
"# Base 1s Imps"
]

The metrics which you want in your report.

For a Facebook Report, you must use the Format dimension set to video or display. You can use the following metrics in these categories for a Facebook Report:

  • Viewability

  • Invalid Traffic

  • Video

  • Display

Viewability Facebook

  • # Impressions

  • % Impressions

  • # Base Impressions

  • % Base Impressions

  • # ≥ 2s

  • % ≥ 2s

  • # Duration-Measurable Imps

  • % Duration-Measurable Imps

  • Avg Time in View (Sec)

  • # 50% Views

  • % 50% Views

  • Total Tracked Ads

Invalid Traffic Facebook

  • # Suspicious

  • % Suspicious

Video Facebook

  • # Pass Thru Views

  • % Pass Thru Views

  • # Unplayed

  • Ad Distribution by Time in View

  • % Ad Distribution by Time in View

  • Avg % Viewed for Played Ads

  • Play count by % Played

  • % Play count by % Played

Display Facebook

  • # Full Views

  • % Full Views

  • # Duration-Measurable Imps

  • % Duration-Measurable Imps

  • # Base 1s Imps

  • % Base 1s Imps

  • # 100% Views

  • % 100% Views

Dimensions and Dimension Filters Facebook

See Sample Dimensions and Dimension Filters for additional examples.

Available for participating advertisers, the Facebook Report supports the following dimensions.

Dimension

Possible Values

Ad

all or specific ads. If you don't specify 'dimensionFilters', then the API groups by all ads.

Ad Set

all or specific ad sets. If you don't specify 'dimensionFilters', then the API groups by all ad sets.

Advertiser

Allows you to get data for multiple teams at once. Use in conjunction with the 'ultimateAdvertiserIds' property.

Campaigns

active

or specific campaigns.

Creative

all or specific creatives. If you don't specify 'dimensionFilters', then the API groups by all creatives.

CTA

Call to Action; for example, 'LEARN_MORE, 'SHOP_NOW', 'DOWNLOAD', etc. You must use

Objectives

when you use CTA.

Date

Use 'dateBreakout' to define the time period. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Device

desktop (1)

smartphone (2)

tablet (3)

connected TV (5)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all devices.

Environment

browser (1)

in-app (2)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all environments.

Format

In 'dimensionFilters', you must set to either:

display

video

Inventory Type

all or specific inventory types. If you don't specify 'dimensionFilters', then the API groups by all inventory types. The types:

Desktop Feed (16)

Mobile Feed (19)

Audience Networking work (Video only, 24)

Instagram (35)

Mobile Video Channel (Video only, 37)

Desktop video channel (Video only, 38)

Mobile instream video (Video only, 46)

Desktop instream video (Video only, 47)

Instagram Stories (49)

Facebook Stories (Video only, 59)

Facebook Watch Feed (Video only, 70)

Objectives

The goal for the ad. For example, 'Sales', 'App Promotion', 'Leads', etc.

Teams

The team IDs you want to group and, or filter upon.

Minimum Filter Facebook

You must set a minimum filter of total tracked ads for a Facebook Report.

See Minimum Filter for more information.

YouTube Report Type

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Reporting_API_ Example_YouTube"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-16"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

YOUTUBE_REPORTS

For example: "reportType": "YOUTUBE_REPORTS"

Metrics YouTube

YouTube Example Metrics:

"metrics": [
"GARM Risk Level",
"GARM Category",
"Impressions"
]

The metrics which you want in your report.

For YouTube Reports, you can use the following metrics in these categories:

  • Brand Safety

  • GARM Risk

Brand Safety YouTube

When the dimension Type is set to brandsafety, you can use the following metrics:

  • Total Eligible Ads for Brand Safety

  • GARM Passed Ads

  • % GARM Passed Ads

  • GARM Floor Failure Ads

  • % GARM Floor Failure Ads

GARM Risk YouTube

When the dimension Type is set to garm, you can use the following metrics:

  • GARM Risk Level (set the level via parameters)

  • GARM Category

  • Impressions (set a minimum impression count via parameters)

Dimensions and Dimension Filters YouTube

See Sample Dimensions and Dimension Filters for additional examples.

Dimension

Possible Values

Campaigns

active

or specific campaigns.

Date

Use 'dateBreakout' to define the time period. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

GVP Apps

Breaks out the report for Google Video Partners app store, app ID, and app name. This dimension is only available when the Type dimension is set to garm and the Inventory Type is set to gvp. You can only use

GVP Apps

or

GVP Full URLs

; you can't use both.

GVP Full URLs

Breaks out the report for Google Video Partners URLs. This dimension is only available when the Type dimension is set to garm and the Inventory Type is set to gvp. You can only use

GVP Apps

or

GVP Full URLs

; you can't use both.

Inventory Type

Inventory Type with a possible dimensionFilters value of either

youtube

or

gvp

(Google Video Partners).

Teams

The team IDs you want to group and, or filter upon.

Type

Type is

required

for a YouTube Report. Possible dimensionFilters value is either

brandsafety

or

garm

; you can't have both brandsafety and garm in the same report. If you select garm, then you can set the

GARM Risk Level

to Floor, High, Medium, and, or Low via

parameters.

Videos

Group and filter for a specific video ID. With the Videos dimension, you can get data for up to 180 days. The Videos dimension is only available if you have the Type set to garm and Inventory Type set to youtube.

Minimum Filter YouTube

You must set a minimum filter of total tracked ads for a YouTube Report.

See Minimum Filter for more information.

Parameters

Parameters Example:

"parameters": {
"GARM Risk Level" : [
"Floor",
"High",
"Medium",
"Low"
],
"Impressions": ">=100"
}

When the dimension Type is set to garm, you can set a parameters GARM Risk Level and, or a minimum impression count of at least 100.

The GARM Risk Level can include the following:

  • Floor

  • High

  • Medium

  • Low

Also, use parameters to set a minimum impression count: "Impressions": ">=100".

YouTube Contextual Suitability Report Type

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Reporting_API_ Example_YouTubeContextualSuitability"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-16"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

YOUTUBE_CONTEXTUAL_AGGREGATE

For example: "reportType": "YOUTUBE_CONTEXTUAL_AGGREGATE"

Metrics YouTube Contextual Suitability

YouTube Contextual Suitability Example Metrics

"metrics": [
"Total Eligible Impressions for Contextual Suitability",
"Family & Parenting - Kids Content Impressions",
"Politics Impressions",
"News Impressions",
"Natural Disasters Impressions"
]

For YouTube Contextual Suitability Reports, you can use the following metrics:

  • Total Eligible Impressions for Contextual Suitability

  • Family & Parenting - Kids Content Impressions

  • Politics Impressions

  • News Impressions

Natural Disasters Impressions

Dimensions and Dimension Filters YouTube Contextual Suitability

YouTube Contextual Suitability

"dimensions": [
"Teams",
"Campaigns",
"Date"
]

See Sample Dimensions and Dimension Filters for additional examples.

Dimension

Possible Values

Teams

The team IDs you want to group and, or filter upon.

Campaigns

active

or specific campaigns.

Date

Use 'dateBreakout' to define the time period. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

YouTube Content Level Contextual Suitability Report Type

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Reporting_API_ Example_YouTubeContentLevelContextualSuitability"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-16"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

YOUTUBE_CONTEXTUAL_CONTENT

For example: "reportType": "YOUTUBE_CONTEXTUAL_CONTENT"

Metrics YouTube Content Level Contextual Suitability

YouTube Content Level Contextual Suitability Example Metrics

"metrics": [
"Impressions"
]

For YouTube Content Level Contextual Suitability Reports, you must use the 'Impressions' metric.

Dimensions and Dimension Filters YouTube Content Level Contextual Suitability

YouTube Content Level Contextual Suitability

"dimensions": [
"Teams",
"Campaigns",
"Videos",
"Contextual Category",
"Date"
]

See Sample Dimensions and Dimension Filters for additional examples.

Dimension

Possible Values

Teams

The team IDs you want to group and, or filter upon.

Campaigns

active

or specific campaigns.

Videos

Group and filter for a specific video ID. With the Videos dimension, you can get data for up to 180 days. You

must

include a Videos dimension and a Contextual Category dimension for a YouTube Content Level Contextual Suitability report.

Contextual Category

All or specific contextual categories. If you don't specify 'dimensionFilters', then the API groups by all contextual categories. You

must

include a Videos dimension and a Contextual Category dimension for a YouTube Content Level Contextual Suitability report.

Date

Use 'dateBreakout' to define the time period. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Parameters

"parameters": {
"Impressions": ">=100"
}

You can set a minimum impression count of at least 100.

Collision Report Type

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Reporting_API_Example_Collisions"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-16"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

COLLISIONS

For example: "reportType": "COLLISIONS"

Metrics Collision

Collision Example Metrics

"metrics": [
"3 Ad Collisions",
"Total Collisions"
]

For Collision Reports, you can use the following metrics:

  • Eligible ads for collisions measurement

  • Eligible rate for collisions measurement

  • 2 Ad Collisions

  • 3 Ad Collisions

  • 4+ Ad Collisions

  • Non-Colliding Ads

  • Total Colliding Ads

  • Total Collisions

  • Total Impressions

Dimensions and Dimension Filters Collisions

Campaigns

"dimensions": [
"Campaigns"
],
"dimensionFilters": [
{
"field": "Campaigns",
"values": ["123456"]
}
]

Campaign Status

"dimensions": [
"Campaigns"
],
"dimensionFilters": [
{
"field": "Campaign Status",
"values": ["Low Traffic"]
}
]

Colliding Media partners

"dimensions": [
"Colliding Media partners"
],
"dimensionFilters": [
{
"field": "Include Partner to Partner",
"values": ["Yes"]
}
],
"thresholdCondition": {
"metric": "Total Colliding Ads",
"value": 10000
}

See Sample Dimensions and Dimension Filters for additional examples.

Dimension

Possible Values

Advertiser

Allows you to get data for multiple teams at once. Use in conjunction with the 'ultimateAdvertiserIds' property.

Campaigns

With the dimensionFilters field 'Campaigns' (active or specific campaigns), or with the dimensionFilters field 'Campaign Status':

Active - filter campaigns running for more than 7 days with at least 1,000 ads, and

running with at least 1,000 ads for at least 7 days, and

running over 10,000 ads for at least one day over the last 7 days

Cancelled - filter deactivated campaigns

Completed - filter inactive campaigns

New - filter campaigns active for 7 days or fewer

Low Traffic - filter only campaigns that had fewer than 1,000 ad views for at least 10 days).

Colliding Media partners

Allows you to see which publishers collided with another publisher. For the dimension 'Colliding Media partners', use the filter field 'Include Partner to Partner' set to

Yes

to see the colliding publishers. If you don't specify 'dimensionFilters', then the 'Include Partner to Partner' is set to

No.

When you use the dimension filter 'Include Partner to Partner', then you

must

set the minimum threshold to 'Total Colliding Ads'.

Date

Use 'dateBreakout' to define the time period. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Domains

If you group by the 'Domains' dimension, then you can't also group by the 'Teams' dimensions.

External Id

External ID.

Media partners

All or specific media partners. If you don't specify 'dimensionFilters', then the API groups by all media partners.

Placements

All or specific placements. If you don't specify 'dimensionFilters', then the API groups by all placements.

Teams

The team IDs you want to group and, or filter upon.

Minimum Filter Collisions

Minimum Colliding Ads Filter Example

"dimensions": [
"Colliding Media partners"
],
"dimensionFilters": [
{
"field": "Include Partner to Partner",
"values": ["Yes"]
}
],
"thresholdCondition": {
"metric": "Total Colliding Ads",
"value": 10000
}

You must set a minimum filter of total tracked ads for a Collision Report. You can set a filter to return only data which meets a minimum threshold of total tracked ads or to the total colliding ads, or you can set to not include any threshold (-1).

When you use 'Colliding Media partners' dimension with the filter ''Include Partner to Partner', then the minimum threshold must be 'Total Colliding Ads'.

Geo Compliance Report Type

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Geo_Compliance"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-16"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

GEO_COMPLIANCE

For example: "reportType": "GEO_COMPLIANCE"

Metrics Geo Compliance

Geo Compliance Example Metrics

"metrics": [
"Total Tracked Ads"
]

For Geo Compliance Reports, you must use the 'Total Tracked Ads' metric.

Dimensions and Dimension Filters Geo Compliance

Country

"dimensions": [
"Teams",
"Country"
]

See Sample Dimensions and Dimension Filters for additional examples.

Dimension

Possible Values

Advertiser

Allows you to get data for multiple teams at once. Use in conjunction with the 'ultimateAdvertiserIds' property.

Campaigns

With the dimensionFilters field 'Campaigns' (active or specific campaigns), or with the dimensionFilters field 'Campaign Status':

Active - filter campaigns running for more than 7 days with at least 1,000 ads, and

running with at least 1,000 ads for at least 7 days, and

running over 10,000 ads for at least one day over the last 7 days

Cancelled - filter deactivated campaigns

Completed - filter inactive campaigns

New - filter campaigns active for 7 days or fewer

Low Traffic - filter only campaigns that had fewer than 1,000 ad views for at least 10 days).

Date

Use 'dateBreakout' to define the time period. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Country

Country. You

must

include a Country, DMA, or State dimension for a Geo Compliance report.

DMA

Designated Market Areas for the United States. You

must

include a Country, DMA, or State dimension for a Geo Compliance report.

External Id

External ID.

Media partners

All or specific media partners. If you don't specify 'dimensionFilters', then the API groups by all media partners.

Placements

All or specific placements. If you don't specify 'dimensionFilters', then the API groups by all placements.

State

United States and Canadian states, provinces, or territories. You

must

include a Country, DMA, or State dimension for a Geo Compliance report.

Teams

The team IDs you want to group and, or filter upon.

Minimum Filter Geo Compliance

Minimum Filter Geo Compliance Example

"thresholdCondition": {
"metric": "Total tracked ads",
"value": -1
}

You must set a minimum filter of total tracked ads for a Geo Compliance Report. You can set a filter to return only data which meets a minimum threshold of total tracked ads or you can set to not include any threshold (-1).

GroupM Fully On Screen Report Type

Only data from teams enabled for GroupM Viewability Measurement is included.

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "GroupM_Fully"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-16"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

GROUP_M

For example: "reportType": "GROUP_M"

Metrics GroupM Fully On Screen

GroupM Fully On Screen Example Metrics

"metrics": [
"Total Impressions",
"% Display Ads Fully on Screen",
"Fully on Screen Display Ads",
"% Videos Fully on Screen",
"Fully on Screen Video Ads",
"GroupM Measured Ads",
"Measured Display Ads",
"Measured Video Ads",
"Total Unblocked Ads",
"Total Billable Ads",
"Viewable Ads",
"TrueView Ads Fully on Screen",
"Measured TrueView Ads Fully on Screen",
"% TrueView Ads Fully on Screen"
]

For GroupM Reports, you can use the following metrics:

  • Total Impressions

  • % Display Ads Fully on Screen

  • Fully on Screen Display Ads

  • % Videos Fully on Screen

  • Fully on Screen Video Ads

  • GroupM Measured Ads

  • Measured Display Ads

  • Measured Video Ads

  • Total Unblocked Ads

  • Total Billable Ads

  • Viewable Ads

  • TrueView Ads Fully on Screen

  • Measured TrueView Ads Fully on Screen

  • % TrueView Ads Fully on Screen

For GroupM Fully On Screen Reports, you must use the 'Total Tracked Ads' metric as a 'thresholdCondition'.

Dimensions and Dimension Filters GroupM Fully On Screen

GroupM Fully On Screen

"dimensions": [
"Teams",
"Placements",
"Campaigns",
"Media partners",
"Device",
"Format",
"Environment",
"Date"
]

See Sample Dimensions and Dimension Filters for additional examples.

Dimension

Possible Values

Campaigns

active

or specific campaigns.

Date

Use 'dateBreakout' to define the time span. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Device

desktop (1)

smartphone (2)

tablet (3)

connected TV (5)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all devices.

Environment

browser (1)

in-app (2)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all environments.

Format

display (1)

video (2)

If you don't specify 'dimensionFilters', then the API groups by all formats.

Media partners

All or specific media partners. If you don't specify 'dimensionFilters', then the API groups by all media partners.

Placements

All or specific placements. If you don't specify 'dimensionFilters', then the API groups by all placements.

Teams

The team IDs you want to group and, or filter upon.

Minimum Filter GroupM Fully On Screen

Minimum Filter GroupM Fully On Screen Example

"thresholdCondition": {
"metric": "Total Tracked Ads",
"value": -1
}

You must set a minimum filter of total tracked ads for a GroupM Fully On Screen Report. You can set a filter to return only data which meets a minimum threshold of total tracked ads or you can set to not include any threshold (-1).

Domain Mismatch Reporting Input File

Uses IAS data for insights on discrepancies between the Bid Domain (the domain the DSP reported) and Measured Domain (the domain IAS detected).

The Domain Mismatch Report is restricted to at most 7 days. Also, this report flags all mismatches where the domain or top-level domain of the Bid Domain and Measured Domain do not match. Cases that may not represent true mismatches are not filtered out (for example: video players, sandboxes, publisher monetization platforms, etc.)

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Domain_Mismatch"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

The Domain Mismatch Report can be at most 7 days.

For example: "reportEnd": "2021-04-06"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

DOMAIN_MISMATCH

For example: "reportType": "DOMAIN_MISMATCH"

Metrics Domain Mismatch

Domain Mismatch Example Metrics

"metrics": [
"Domain Mismatch Count",
"Domain Mismatch Rate",
"Subdomain Mismatch Count",
"Subdomain Mismatch Rate",
"Total Mismatch Count",
"Total Mismatch Rate",
"Measured Domain Total Tracked Ads"
]

For Domain Mismatch Reports, you can use the following metrics:

  • Domain Mismatch Count

  • Domain Mismatch Rate

  • Subdomain Mismatch Count

  • Subdomain Mismatch Rate

  • Total Mismatch Count (required for a Domain Mismatch report)

  • Total Mismatch Rate

  • Measured Domain Total Tracked Ads

For Domain Mismatch Reports, you must use the 'Measured Domain Total Tracked Ads' metric as a 'thresholdCondition'.

Ultimate Advertiser IDs

Ultimate Advertiser IDs

"metrics": [
"Total Mismatch Count"
],
"dimensions": [
"Advertiser"
],
"ultimateAdvertiserIds":[1,6]

'ultimateAdvertiserIds' is used in conjunction with the 'Advertiser' dimension, this setting allows you to get data for many teams with a single advertiser ID. Contact your IAS representative for the ultimate advertiser IDs.

Dimensions and Dimension Filters Domain Mismatch

Domain Mismatch

"dimensions": [
"Advertiser",
"Teams",
"Bid Domain",
"Campaigns",
"Media partners",
"Placements",
"Measured Domain",
"Channel (Exchange)",
"Date",
"DSP",
"DSP Campaign",
"DSP Deal",
"DSP Placement (Line item)",
"DSP Publisher",
"Device",
"Format",
"Environment",
"Mismatch Reason"
]

See Sample Dimensions and Dimension Filters for additional examples.

Dimension

Possible Values

Advertiser

Allows you to get data for multiple teams at once. Use in conjunction with the 'ultimateAdvertiserIds' property.

Bid Domain

The domain the DSP reported and is

required

for a Domain Mismatch report. Bid Domain does not support a dimension filter.

Media partners

All or specific media partners. If you don't specify 'dimensionFilters', then the API groups by all media partners.

Placements

All or specific placements. If you don't specify 'dimensionFilters', then the API groups by all placements.

Campaigns

active

or specific campaigns.

Channel (Exchange)

Channel.

Date

Use 'dateBreakout' to define the time span. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

If not specified, 'Date' groups by PERIOD.

DSP

DSP Value - DSP Name:

1 - Amobee

2 - Xandr

3 - DV360

8 - MediaMath

9 - TTD

11 - Adobe

12 - AdForm

26 - Zeta Global

28 - Adelphic

30 - VMG

33 - Amazon

58 - Beeswax

DSP Campaign

DSP Campaign.

DSP Deal

DSP Deal.

DSP Placement (Line item)

DSP Placement.

Device

desktop (1)

smartphone (2)

tablet (3)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all devices.

Format

display (1)

video (2)

If you don't specify 'dimensionFilters', then the API groups by all formats.

Environment

browser (1)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all environments.

Mismatch Reason

Domain Specialization Increase

Domain Specialization Decrease

Subdomain Variation

Advertising Network Domains

Application Names in Domains

Application IDs in Domains

Invalid Domain

General Mismatch

DSP Publisher

DSP Publisher.

Measured Domain

The domain IAS detected and is

required

for a Domain Mismatch report. Measured Domain does not support a dimension filter.

Teams

The team IDs you want to group and, or filter upon.

Minimum Filter Domain Mismatch

Minimum Filter Domain Mismatch Example

"thresholdCondition": {
"metric": "Measured Domain Total Tracked Ads",
"value": -1
}

You must set a minimum filter of total tracked ads for a Domain Mismatch Report. You can set a filter to return only data which meets a minimum threshold of measured domain total tracked ads or you can set to not include any threshold (-1).

TikTok Reporting Reporting Input File

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "TikTok_Reporting"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-06"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

TIKTOK_REPORTS

For example: "reportType": "TIKTOK_REPORTS"

Metrics TikTok Reporting

TikTok Reporting Example Brand Safety Metric

"metrics": [
"Failed Ads"
]

TikTok Reporting Example Video-Level Metrics

"metrics": [
"Total Tracked Ads",
"GARM Suitability Category",
"GARM Floor Category",
"Risk Level",
"Suitability Category"
]

For TikTok Reporting, you can use the following metrics for Brand Safety or Video-Level:

Brand Safety: Failed Ads

Video-Level:

  • Total Tracked Ads

  • GARM Suitability Category

  • GARM Floor Category

  • Risk Level

  • Suitability Category

Dimensions and Dimension Filters TikTok Reporting

TikTok Reporting

"dimensions": [
"TikTok Report Type",
"Advertiser",
"Teams",
"Campaigns",
"Date",
"Format",
"Device"
]
"dimensionFilters": [
{
"field": "TikTok Report Type",
"values": [
"reasonElement"
]
}
]
or
"dimensionFilters": [
{
"field": "TikTok Report Type",
"values": [
"video"
]
}
]

See Sample Dimensions and Dimension Filters for additional examples.

Dimension

Possible Values

Advertiser

Allows you to get data for multiple teams at once. Use in conjunction with the 'ultimateAdvertiserIds' property.

Campaigns

active

or specific campaigns.

Channel (Exchange)

Channel.

Date

Use 'dateBreakout' to define the time span. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Device

desktop (1)

smartphone (2)

tablet (3)

connected TV (5)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all devices.

DSP

DSP Value. This dimension is only available when the 'TikTok Report Type' dimension is set to

reasonElement

, and with the TikTok Brand Safety metric (Failed Ads).

DSP Campaign

DSP Campaign. This dimension is only available when the 'TikTok Report Type' dimension is set to

reasonElement

, and with the TikTok Brand Safety metric (Failed Ads).

DSP Deal

DSP Deal. This dimension is only available when the 'TikTok Report Type' dimension is set to

reasonElement

, and with the TikTok Brand Safety metric (Failed Ads).

DSP Placement (Line item)

DSP Placement. This dimension is only available when the 'TikTok Report Type' dimension is set to

reasonElement

, and with the TikTok Brand Safety metric (Failed Ads).

DSP Publisher

DSP Publisher. This dimension is only available when the 'TikTok Report Type' dimension is set to

reasonElement

, and with the TikTok Brand Safety metric (Failed Ads).

Floor Failures

TikTok Brand Safety dimension which can only be used with the TikTok Brand Safety metric (Failed Ads).

Format

display (1)

video (2)

If you don't specify 'dimensionFilters', then the API groups by all formats.

Teams

The team IDs you want to group and, or filter upon.

TikTok Report Type

Set the dimension filter field to

TikTokReportType

and the values as

reasonElement

or

video

. You must use 'TikTok Report Type' for a TIKTOK_REPORTS report type.

Video

TikTok video dimension which can only be used with the TikTok Video-Level metrics (Total Tracked Ads, GARM Suitability Category, GARM Floor Category, Risk Level, or Suitability Category).

Minimum Filter TikTok Reporting

Minimum Filter TikTok Reporting Example Brand Safety:

"thresholdCondition": {
"metric": "Failed Ads",
"value": -1
}

Minimum Filter TikTok Reporting Example Video-Level:

"thresholdCondition": {
"metric": "Total Tracked Ads",
"value": -1
}

You must set a minimum filter of "Failed Ads" for the Brand Safety metric (Failed Ads), and "Total Tracked Ads" for Video-Level metrics (Total Tracked Ads, GARM Suitability Category, GARM Floor Category, Risk Level, or Suitability Category) with TikTok Reporting.

You can set a filter to return only data which meets a minimum threshold or you can set to not include any threshold (-1).

Total Visibility Reporting Input File

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "TV_Reporting"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-06"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

TOTAL_VISIBILITY_REPORTING

For example: "reportType": "TOTAL_VISIBILITY_REPORTING"

Metrics Total Visibility Reporting

Total Visibility Reporting Example:

"metrics": [
"Total Visibility Tracked Ads",
"Total Visibility Tracked Spend (USD)",
"eCPM (USD)",
"qCPM (USD)",
"qCPM delta (USD)",
"Quality Impressions",
"Quality Impressions %",
"Quality Spend %",
"Quality Spend (USD)",
"Unsafe Impressions",
"Unsafe Impressions %",
"Unsafe Spend (USD)",
"Unsafe Spend %",
"Unviewable Impressions (MRC)",
"Unviewable Impressions (MRC) %",
"Unviewable (MRC) Spend (USD)",
"Unviewable (MRC) Spend %",
"Invalid Traffic Impressions",
"Invalid Traffic Impressions %",
"Invalid Traffic Spend (USD)",
"Invalid Traffic Spend %",
"Out of Geo Impressions",
"Out of Geo Impressions %",
"Out of Geo Spend (USD)",
"Out of Geo Spend %"
]

For Total Visibility, you can use the following metrics:

  • Total Visibility Tracked Ads

  • Total Visibility Tracked Spend (USD)

  • eCPM (USD)

  • qCPM (USD)

  • qCPM delta (USD)

  • Quality Impressions

  • Quality Impressions %

  • Quality Spend %

  • Quality Spend (USD)

  • Unsafe Impressions

  • Unsafe Impressions %

  • Unsafe Spend (USD)

  • Unsafe Spend %

  • Unviewable Impressions (MRC)

  • Unviewable Impressions (MRC) %

  • Unviewable (MRC) Spend (USD)

  • Unviewable (MRC) Spend %

  • Invalid Traffic Impressions

  • Invalid Traffic Impressions %

  • Invalid Traffic Spend (USD)

  • Invalid Traffic Spend %

  • Out of Geo Impressions

  • Out of Geo Impressions %

  • Out of Geo Spend (USD)

  • Out of Geo Spend %

Dimensions and Dimension Filters Total Visibility Reporting

Total Visibility Reporting:

"dimensions": [
"Teams",
"Campaigns",
"DSP",
"DSP Campaign",
"SSP",
"DSP Placement (Line item)",
"DSP Publisher",
"DSP Deal",
"Date",
"Device",
"Format"
]
"dimensionFilters": [
{
"field": "Device",
"values": [
"0",
"1",
"2"
]
}
]

See Sample Dimensions and Dimension Filters for additional examples.

The Date dimension uses the dateBreakout property to set the grouping.

Dimension

Possible Values

Campaigns

active

or specific campaigns.

Date

Use 'dateBreakout' to define the time span. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Device

desktop (1)

smartphone (2)

tablet (3)

connected TV (5)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all devices.

DSP

DSP Value.

DSP Campaign

DSP Campaign.

DSP Deal

DSP Deal.

DSP Placement (Line item)

DSP Placement.

DSP Publisher

DSP Publisher.

Format

display (1)

video (2)

If you don't specify 'dimensionFilters', then the API groups by all formats.

SSP

Supply Side Platform.

Teams

The team IDs you want to group and, or filter upon.

Custom Metrics

Custom Metrics Example:

"customMetrics": {
"id":"123",
"name":"name123"
}

You need to declare the 'id' and the 'name'. Custom Metrics are only available for a Performance Report or Total Visibility Report.

Contact your IAS representative for the name and ID for the custom metrics.

Attention Reporting Input File

The input file to create a report is in JSON format with the following properties.

Report Name

Select a name which best describes your report.

For example: "reportName": "Attention_Reporting"

Report Team IDs

IAS only shows data for the requested team ID. If you attempt to get data for teams you don't have access to, the report creation fails.

For example: "reportTeamIds": [ 12345]

Report Start

For example: "reportStart": "2021-03-31"

Report End

For example: "reportEnd": "2021-04-06"

File Type

CSV

The Reporting API supports CSV output file format for the report.

For example: "fileType": "CSV"

Report Type

ATTENTION_REPORTING

For example: "reportType": "ATTENTION_REPORTING"

Metrics Attention Reporting

Attention Reporting Example Metrics:

"metrics": [
"Total Tracked Ads",
"Eligible Ads for Ad Density",
"Average Ad Density",
"Ad Share of Screen Distribution",
"Attention Score",
"Visibility Score",
"Situation Score",
"Interaction Score",
"Subcategory Comparison",
"Pause/Unpause",
"User Scroll",
"Volume Up/Down/Mute",
"Click to play ads",
"Auto Play Ads",
"Time-in-View Distribution (Display)",
"Average Time in View (Display)",
"Eligible Ads for Viewability Measurement",
"Measured Ads",
"Measured Rate (out of Ads)",
"Viewable Impressions",
"Viewable Rate",
"Full-Screen Plays",
"Valid Video Ads",
"Valid quartiles",
"Valid quartiles rate (% of Valid Video Ads)",
"Valid Viewable Video Impressions",
"Viewable valid quartiles",
"Viewable valid quartiles rate (% of Valid Viewable Video Impressions)"
]

For Attention Reporting, you can use the following metrics, grouped in the following areas:

Summary: Total Tracked Ads

Situation

  • Eligible Ads for Ad Density

  • Average Ad Density

  • Ad Share of Screen Distribution

Attention Overview

  • Eligible Impressions For Attention

  • Attention Score

  • Visibility Score

  • Situation Score

  • Interaction Score

  • Subcategory Comparison

Interaction

  • Pause/Unpause

  • User Scroll

  • Volume Up/Down/Mute

  • Click to play ads

  • Auto Play Ads

Visibility

  • Time-in-View Distribution (Display)

  • Average Time in View (Display)

  • Eligible Ads for Viewability Measurement

  • Measured Ads

  • Measured Rate (out of Ads)

  • Viewable Impressions

  • Viewable Rate

  • Full-Screen Plays

  • Valid Video Ads

  • Valid quartiles

  • Valid quartiles rate (% of Valid Video Ads)

  • Valid Viewable Video Impressions

  • Viewable valid quartiles

  • Viewable valid quartiles rate (% of Valid Viewable Video Impressions)

Dimensions and Dimension Filters Attention Reporting

Attention Reporting:

"dimensions": [
"Campaigns",
"Device"
]

See Sample Dimensions and Dimension Filters for additional examples.

Dimension

Possible Values

Advertiser

Allows you to get data for multiple teams at once. Use in conjunction with the 'ultimateAdvertiserIds' property.

Campaigns

active

or specific campaigns.

Channel (Exchange)

Channel.

Date

Use 'dateBreakout' to define the time span. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Device

desktop (1)

smartphone (2)

tablet (3)

If you don't specify 'dimensionFilters', then the API groups by all devices.

Domains

If you group by the 'Domains' dimension, then you can't also group by the 'Teams' dimension.

DSP

DSP Value.

DSP Campaign

DSP Campaign.

DSP Deal

DSP Deal.

DSP Placement (Line item)

DSP Placement.

DSP Publisher

DSP Publisher.

Environment

browser (1)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all environments.

Format

display (1)

video (2)

If you don't specify 'dimensionFilters', then the API groups by all formats.

Media partners

All or specific media partners. If you don't specify 'dimensionFilters', then the API groups by all media partners.

Placements

All or specific placements. If you don't specify 'dimensionFilters', then the API groups by all placements.

Teams

The team IDs you want to group and, or filter upon. If selected, you can't also use the 'Domains' dimension.

Minimum Filter Attention Reporting

Minimum Filter Attention Reporting Example

"thresholdCondition": {
"metric": "Total Tracked Ads",
"value": -1
}

You may set a minimum filter of total tracked ads for Attention Reporting.

You can set a filter to return only data which meets a minimum threshold of total tracked ads or you can set to not include any threshold (-1).

Dimensions and Dimension Filters Attention Reporting

Attention Reporting:

"dimensions": [
"Teams",
"Campaigns",
"DSP",
"DSP Campaign",
"SSP",
"DSP Placement (Line item)",
"DSP Publisher",
"DSP Deal",
"Date",
"Device",
"Format"
]
"dimensionFilters": [
{
"field": "Device",
"values": [
"0",
"1",
"2"
]
}
]

See Sample Dimensions and Dimension Filters for additional examples.

The Date dimension uses the dateBreakout property to set the grouping.

Dimension

Possible Values

Campaigns

active

or specific campaigns.

Date

Use 'dateBreakout' to define the time span. Possible values for 'dateBreakout':

PERIOD (the time between the reportStart and reportEnd values)

BY_DAY

BY_WEEK

BY_MONTH

If not specified, 'Date' groups by PERIOD.

Device

desktop (1)

smartphone (2)

tablet (3)

connected TV (5)

unknown (9)

If you don't specify 'dimensionFilters', then the API groups by all devices.

DSP

DSP Value.

DSP Campaign

DSP Campaign.

DSP Deal

DSP Deal.

DSP Placement (Line item)

DSP Placement.

DSP Publisher

DSP Publisher.

Format

display (1)

video (2)

If you don't specify 'dimensionFilters', then the API groups by all formats.

SSP

Supply Side Platform.

Teams

The team IDs you want to group and, or filter upon.

Parameters

The parameter 'Attention Exclude Focus' is a boolean which when set to 'true', doesn't include Lumen metrics when calculating 'Attention Score', 'Interaction Score', and 'Eligible Impressions For Attention'. When you don't set the key to 'Attention Exclude Focus', it defaults to false and 'Attention Score', 'Interaction Score', and 'Eligible Impressions For Attention' use Lumen data in the calculations.

Example Setting Parameters:

"parameters": [
{
"key": "Attention Exclude Focus",
"value": false
}
]

Check Status

Returns the status of the report using the ID returned on report creation. The status is:

  • READY

  • SUBMITTED

  • PENDING

  • NO_RESULTS

  • ERROR

Curl

curl -vX --location --request GET https://data.integralplatform.com/report-status?id={reportId} --header "Authorization: Bearer ${TOKEN}"

Input

Name

In

Type

Required

id

query

integer(int64)

true

Outputs

Name

Type

Notes

id

integer(int64)


status

string

SUBMITTED

PENDING

NO_RESULTS

ERROR

READY

Check Status Example Output

{
"id": 12345,
"status": "READY"
}

Download Report

Get the data for the report using the ID return in the report creation. The fields in the output depends on the metrics in the report. Use Check Status to learn when you can download the report. You can only call the Download Report API, at most:

  • five times in a minute,

  • 20 times in a hour, and

  • 100 times in a day.

Example Response Header for Custom Rates

< x-ratelimit-limit-minute: 5
< x-ratelimit-remaining-minute: 4
< x-ratelimit-reset-minute: 60
< x-ratelimit-limit-hour: 100
< x-ratelimit-remaining-hour: 97
< x-ratelimit-reset-hour: 3168
< x-ratelimit-limit-day: 500
< x-ratelimit-remaining-day: 495
< x-ratelimit-reset-day: 39571
< ratelimit-limit: 5;w=60, 100;w=3600, 500;w=86400
< ratelimit-remaining: 4;w=60, 97;w=3600, 495;w=86400
< ratelimit-reset: 60

For increased limits, contact your IAS representative. You can get the value for your custom rates in the response header. Use the verbose option (-v) in the curl command to see the response header.

Curl

curl --location --request GET 'https://data.integralplatform.com/report-download?id={reportId}' -o <output.csv> --header "Authorization:Bearer ${TOKEN}"

Input

Name

In

Type

Required

id

query

integer(int64)

true

Outputs

Name

Type

Notes

report

string

Contents of the report in the format as defined for the report.

Example Output

"Campaign Id","Campaign","IAS Placement Id","Ad Server Placement Id","Placement","Media partner Id","Media partner","Team Id","Team Name","Environment","Total Tracked Ads","Eligible Ads For Invalid Traffic Detection","Invalid Traffic","Invalid Traffic Rate","Valid Traffic","Valid Traffic Rate","Blocked Invalid Traffic","% of Invalid Traffic Blocked","Unblocked Invalid Traffic","% of Invalid Traffic Unblocked","Adult Ads","% of Adult Ads","Alcohol Ads","% of Alcohol Ads","% of Hate Speech Ads"
"123456","Free-Spring_","0","","Unknown","54321","Acme - Partner","12437”,"Tinstle Media","Browser","12345678","12345678","22222","0.16","29633805","99.84","","","","","","","","",""

`"555555","Local-Impact","23713088","298424093","dynamic preroll","16829","Dynamic","12437","Media","Browser","11968968","11968968","60046","0.50","11908922","99.50","57142","95.16","2904","4.84","405","0.00","23245","0.19","0.23"

Get Teams

To retrieve all the teams associated with a client you are entitled to view.

Curl

curl -vX --location --request GET https://data.integralplatform.com/report-dimensions/teams --header "Authorization: Bearer ${TOKEN}"

Input

Not applicable.

Outputs

Name

Type

Notes

id

integer(int64)


name

string

The team name.

status

string

ACTIVE or INACTIVE

Get Teams Example Output

[
{
"id": 12345,
"name": "Acme",
"status": "ACTIVE"
},
{
"id": 12346,
"name": "Acme 2",
"status": "ACTIVE"
}
]

Get Media Partner

To retrieve media partners.

Curl

curl -vX --location --request GET https://data.integralplatform.com/report-dimensions/mediapartners?teams=123,12345&start=2021.03.31&end=2021.04.07 --header "Authorization: Bearer ${TOKEN}"

Inputs

Name

In

Type

Required

Description

teams

query

array(integer)

true

Comma separate the various teams.

start

query

string (date-time)

true

YYYY.MM.DD For example: 2021.03.31

end

query

string (date-time)

true

YYYY.MM.DD For example: 2021.04.07

Outputs

Name

Type

mediaPartnerId

integer(int64)

mediaPartner

string

totalImps

integer(int64)

Get Media Partner Example Output:

[
{
"mediaPartnerId": 54321,
"mediaPartner": "Acme 2",
"totalImps": 282555
},
{
"mediaPartnerId": 12345,
"mediaPartner": "Acme",
"totalImps": 31770
}
]

Get Campaigns

To retrieve the campaigns for teams during a specific date span.

Curl

curl -vX --location --request GET https://data.integralplatform.com/report-dimensions/campaigns?teams=123,12345&start=2021.03.31&end=2021.04.07 --header "Authorization: Bearer ${TOKEN}"

Inputs

Name

In

Type

Required

Description

teams

query

array(integer)

true

Comma separate the various teams.

start

query

string (date-time)

true

YYYY.MM.DD For example: 2021.03.31

end

query

string (date-time)

true

YYYY.MM.DD For example: 2021.04.07

Outputs

Name

Type

campaignId

integer(int64)

campaign

string

totalImps

integer(int64)

Get Campaigns Example Output:

[
{
"campaignId": 111111,
"campaign": "Acme",
"totalImps": 53364
},
{
"campaignId": 222222,
"campaign": "Acme 2",
"totalImps": 133
}
]

Get Placements

Get the placements for teams during a date span.

Curl

curl -vX --location --request GET https://data.integralplatform.com/report-dimensions/placements?teams=123,12345&start=2021.03.31&end=2021.04.07 --header "Authorization: Bearer ${TOKEN}"

Inputs

Name

In

Type

Required

Description

teams

query

array(integer)

true

Comma separate the various teams.

start

query

string (date-time)

true

YYYY.MM.DD For example: 2021.03.31

end

query

string (date-time)

true

YYYY.MM.DD For example: 2021.04.07

Outputs

Name

Type

Notes

placementId

integer(int64)

Placement ID.

placement

string

The placement.

totalImps

integer(int64)

Total impressions.


Get Placements Example Output

[
{
"placementId": 12345678,
"placement": "Acme_Programmatic",
"totalImps": 18263
},
{
"placementId": 12345679,
"placement": "Acme_Programmatic2",
"totalImps": 17794
}
]

Sample Dimensions & Dimension Filters

The Date dimension uses the dateBreakout property to set the grouping. See each report type for more information on the possible values. Also, for Inventory Type, see Dimensions and Dimension Filters Facebook for the various values for the inventory type.

See the following for potential values for the Dimensions and Dimension Filters:

  • Performance Report

  • Brand Suitability Failure Report

  • Facebook Report

  • YouTube Report

  • Collision Report

  • Geo Compliance Report

  • GroupM Fully On Screen Report

  • Domain Mismatch Report

  • TikTok Reporting

  • Total Visibility Reporting

  • Attention Reporting

Ad

"dimensions" : [
"Format",
"Ad"
]

Ad, Setting a Filter

"dimensions" : [ "Format", "Ad" ] ,
"dimensionFilters" : [
{
"field" : "Ad" ,
"values" : [
"123456789",
"123467895"
]
}
]

Ad Set

"dimensions" : [
"Format",
"Ad Set"
]

Ad Set, Setting a Filter

"dimensions" : [
"Format",
"Ad Set"
],
"dimensionFilters" : [
{
"field" : "Ad Set",
"values" : [
"123456789",
"123467895"
]
}
]

Advertiser

"metrics": [
"Total tracked ads"
],
"dimensions": [
"Advertiser"
],
"ultimateAdvertiserIds":[1]

Apps

"dimensions" : [ "Apps" ]

Campaigns

"dimensions" : [
"Campaigns"
],
"dimensionFilters" : [
{
"field" : "Campaigns",
"values" : [
"active"
]
}
]

Campaigns, Setting a Filter

"dimensions" : [
"Campaigns"
],
"dimensionFilters" : [
{
"field" : "Campaigns",
"values" : [
"12345",
"12346"
]
}
]

Campaign Status for Collision Report only

"dimensions": [
"Campaigns"
],
"dimensionFilters": [
{
"field": "Campaign Status",
"values": [
"Cancelled"
]
}
]

Channel (Exchange)

"dimensions" : [
"Channel (Exchange)"
]

Colliding Media partners

"dimensions": [
"Colliding Media partners"
],
"dimensionFilters": [
{
"field": "Include Partner to Partner",
"values": [
"Yes"
]
}
],
"thresholdCondition": {
"metric": "Total Colliding Ads",
"value": -1
}

Contextual Segment

"dimensions" : [
"DSP",
"DSP Campaigns",
"Contextual Segment"
]
"dimensionFilters" : [
{
"field" : "Contextual Segments",
"values" : [
"3000000",
"3000001"
]
}
]

Country for Geo Compliance Report only

"dimensions": [
"Date",
"Country"
]

Creative

"dimensions" : [
"Format",
"Creative"
]

Creative, Setting a Filter

"dimensions" : [
"Format",
"Creative"
],
"dimensionFilters" : [
{
"field" : "Creative",
"values" : [
"123456789",
"123467895"
]
}
]

Date

"dimensions" : [
"Date"
],
"dateBreakout" : "BY_MONTH"

Device

"dimensions" : [
"Device"
],
"dimensionFilters" : [
{
"field" : "Device",
"values" : [
"1",
"3",
"9"
]
}
]

DMA for Geo Compliance Report only

"dimensions": [
"Date",
"DMA"
]

Domains

"dimensions" : [
"Domains"
]

DSP

"dimensions" : [
"DSP"
],
"dimensionFilters" : [
{
"field" : "DSP",
"values" : [
"2"
]
}
]

DSP Campaigns

"dimensions" : [
"DSP Campaigns"
]

DSP Deal

"dimensions" : [
"DSP Deal"
]

DSP Placements (Line item)

"dimensions" : [
"DSP Placement (Line item)"
]

DSP Publisher

"dimensions" : [
"DSP Publisher"
]

Environment

"dimensions" : [
"Environment"
],
"dimensionFilters" : [
{
"field" : "Environment",
"values" : [
"2"
]
}
]

External ID

"dimensions" : [
"External Id"
]

Format for Performance and Brand Suitability Reports

"dimensions" : [
"Format"
],
"dimensionFilters" : [
{
"field" : "Format",
"values" : [
"2"
]
}
]

Format for Facebook Reports

"dimensions" : [
"Format"
],
"dimensionFilters" : [
{
"field" : "Format",
"values" : [
"video"
]
}
]

Format (Facebook) and Inventory Type

"dimensions" : [
"Format",
"Inventory Type"
],
"dimensionFilters" : [
{
"field" : "Format",
"values" : [
"video"
]
},
{
"field" : "Inventory Type",
"values" : [
"16"
]
}
]

GVP Apps (YouTube)

"dimensions" : [
"GVP Apps",
"Type",
"Inventory Type"
],
"dimensionFilters" : [
{
"field" : "Type",
"values" : [
"garm"
]
},
{
"field" : "Inventory Type",
"values" : [
"gvp"
]
}
]

GVP Full URLs (YouTube)

"dimensions" : [
"GVP Full URLs",
"Type",
"Inventory Type"
],
"dimensionFilters" : [
{
"field" : "Type",
"values" : [
"garm"
]
},
{
"field" : "Inventory Type",
"values" : [
"gvp"
]
}
]

Inventory Type (YouTube)

"dimensions" : [
"Inventory Type"
],
"dimensionFilters" : [
{
"field" : "Inventory Type",
"values" : [
"youtube"
]
}
]

Contextual Suitability Category (YouTube Content Level Contextual Suitability)

"dimensions": [
"Video",
"Contextual Suitability Category",
"Teams"
],
"metrics": [
"Contextual Suitability Category"
],
"dimensionFilters": [
{
"fields": [
"Impressions"
],
"operator": "EQUALS",
"values": [
">=100"
]
},
{
"fields": [
"Contextual Suitability Category"
],
"operator": "EQUALS",
"values": [
"Family & Parenting - Kids Content",
"Politics",
"Natural Disasters"
]
}
]

Media partners

"dimensions" : [
"Media partners"
],
"dimensionFilters" : [
{
"field" : "Media partners",
"values" : [
"1234",
"1235"
]
}
]

Placements

"dimensions" : [
"Placements"
],
"dimensionFilters" : [
{
"field" : "Placements",
"values" : [
"1234567",
"123"
]
}
]

Segment

"dimensions" : [
"Segment"
]

State for Geo Compliance Report only

"dimensions": [
"Date",
"State"
]

Teams

"dimensions" : [
"Teams"
]

TikTok Brand Safety

"dimensions": [
"TikTok Report Type",
"Floor Failures",
"Advertiser"
,
"dimensionFilters": [
{
"field": "TikTok Report Type",
"values": [
"reasonElement"
]
}
]

TikTok Video-Level

"dimensions": [
"TikTok Report Type",
"Video",
"Advertiser"
],
"dimensionFilters": [
{
"field": "TikTok Report Type",
"values": [
"video"
]
}
]

Type

"dimensions" : [
"Type"
],
"dimensionFilters" : [
{
"field" : "Type",
"values" : [
"garm"
]
}
]

Videos

"dimensions" : [
"Videos",
"Type",
"Inventory Type"
],
"dimensionFilters" : [
{
"field" : "Video Id",
"values" : [
"DHL05wvx9fI"
]
},
{
"field" : "Type",
"values" : [
"garm"
]
},
{
"field" : "Inventory Type",
"values" : [
"youtube"
]
}
]

Sample Reports

In order to use these sample reports, you need to replace 'reportTeamIds' to a valid value. If you use team IDs which you aren't authorized to use, the report creation fails.

These samples use the team IDs: 12345, 12346, and 12347 which you need to change for the report creation to work properly.

Generic Report Creation

{
"reportName": "Reporting_API_Example_Generic",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "IAS_PERFORMANCE",
"fileType": "CSV",
"metrics": [
"Invalid Traffic",
"Not Viewable Ads"
],
"dimensions": [
"Campaigns",
"Placements",
"Media partners",
"Teams",
"Environment",
"Date"
],
"dateBreakout": "BY_DAY"
}

This report uses six dimensions and groups the data by day. This report uses two metrics but you can use any of the metrics defined in Performance Report Type, Metrics.

Group by Environment (Browser and In-App)

{
"reportName": "Reporting_API_Example_Environment",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "IAS_PERFORMANCE",
"fileType": "CSV",
"metrics": [
"Invalid Traffic",
"Not Viewable Ads"
],
"dimensions": [
"Environment"
],
"dimensionFilters": [
{
"field": "Environment",
"values": [
"1",
"2"
]
}
]
}

This report uses the Environment dimension and then filtering on:

  • 1 (browser)

  • 2 (in-app).

See Performance Report for more information on the Environment values.

Group by Teams and DSP

{
"reportName": "Reporting_API_Example_Teams_DSP",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "IAS_PERFORMANCE",
"fileType": "CSV",
"metrics": [
"Invalid Traffic",
"Not Viewable Ads"
],
"dimensions": [
"Teams",
"DSP"
],
"dimensionFilters": [
{
"field": "DSP",
"values": [
"2"
]
}
]
}

This report uses two dimensions, grouping data on:

  • Teams

  • DSP

Also, this report filters to see a specific DSP (2 = Xandr).

See Performance Report for more information on the DSP values.

Group by Media Partners

See Performance Report for more information.

Group by Media Partners, All

{
"reportName": "Reporting_API_Example_MediaPartners",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "IAS_PERFORMANCE",
"fileType": "CSV",
"metrics": [
"Invalid Traffic",
"Not Viewable Ads"
],
"dimensions": [
"Media partners"
]
}

By not setting a dimensionFilters for Media partners, the Reporting API returns all media partners.

Group by Media Partners, Specific Media partners

{
"reportName": "Reporting_API_Example_Specific_Media_Partners",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "IAS_PERFORMANCE",
"fileType": "CSV",
"metrics": [
"Invalid Traffic",
"Not Viewable Ads"
],
"dimensions": [
"Media partners"
],
"dimensionFilters": [
{
"field": "Media partners",
"values": [
"12345",
"12346"
]
}
]
}

Here, dimensionFilters lists which values to return for the 'Media partners' field.

Group by Placements

See Performance Report for more information on the placement dimension.

Group by Placements, All

{
"reportName": "Reporting_API_Example_Placements",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "IAS_PERFORMANCE",
"fileType": "CSV",
"metrics": [
"Invalid Traffic",
"Not Viewable Ads"
],
"dimensions": [
"Placements"
]
}

In not setting a dimensionFilters for Placements, the Reporting API returns all placements.

Specific

{
"reportName": "Reporting_API_Example_Specific_Placements",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "IAS_PERFORMANCE",
"fileType": "CSV",
"metrics": [
"Invalid Traffic",
"Not Viewable Ads"
],
"dimensions": [
"Placements"
],
"dimensionFilters": [
{
"field": "Placements",
"values": [
"12345678",
"12"
]
}
]
}

Here, dimensionFilters lists which values to return for the 'Placements' field.

Quality Impressions Report

{
"reportName": "Quality_Impressions_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "IAS_PERFORMANCE",
"fileType": "CSV",
"metrics": [
"Total tracked ads",
"Eligible ads for quality impressions",
"Eligible rate for quality impressions",
"Quality impressions",
"Quality impressions rate",
"Non-quality ads",
"Non-quality rate",
"Non-quality blocked ads",
"Non-Quality Not Viewable Ads",
"% Non quality: not viewable",
"Failed brand safety ads",
"% Non quality: failed brand safety",
"Non-Quality Invalid Traffic Ads",
"% Non quality: IVT",
"Non-Quality Out of Geo Ads",
"% Non quality: Out of geo"
],
"parameters": {
"Quality Criteria Geo": true,
"Quality Criteria Viewability": true
},
"dimensions": [
"Campaigns"
]
}

This sample uses the Quality Impressions metrics which requires you use 'Total tracked ads' as one of the metrics.

See Parameters for more information on setting the Quality Criteria Geo and Quality Criteria Viewability.

Brand Suitability Failure Report

{
"reportName": "BrandSuitability_Report_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "FAILED_BY_BRAND_SUITABILITY_PROFILE",
"fileType": "CSV",
"metrics": [
"Failed ads"
],
"dimensions": [
"Segment"
],
"dimensionFilters": []
}

This report uses 'Failed ads' which is the only metric available for this report. Also, Segment is a required dimension.

See Brand Suitability Failure Report Type for more information.

Facebook Report

{
"reportName": "Facebook_Report_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "FACEBOOK_VIEWABILITY",
"fileType": "CSV",
"metrics": [
"# Impressions"
],
"dimensions": [
"Format",
"Creative"
],
"dimensionFilters": [
{
"field": "Format",
"values": [
"video"
]
}
],
"thresholdCondition":
{
"metric": "Total tracked ads",
"value": -1
}
}

You must set 'Format' as a dimension with the dimensionFilters set to either display or video.

Also, you must set a minimum filter of total tracked ads. You may set 'Total Tracked ads' to a specific threshold, or not to include any threshold (-1).

See Facebook Report Type for more information.

YouTube Report

{
"reportName": "YouTube_Report_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "YOUTUBE_REPORTS",
"fileType": "CSV",
"metrics": [
"GARM Risk Level",
"GARM Category",
"Impressions"
],
"dimensions": [
"Videos",
"Inventory type",
"Type"
],
"dimensionFilters": [
{
"field": "Video Id",
"values": [
"DHL05wvx9fI"
]
},
{
"field": "Type",
"values": [
"garm"
]
},
{
"field": "Inventory Type",
"values": [
"youtube"
]
}
],
"parameters": {
"GARM Risk Level" : [
"Floor",
"High",
"Medium",
"Low"
],
"Impressions": ">=100"
},
"thresholdCondition":
{
"metric": "Total tracked ads",
"value": -1
}
}

You must set 'Type' as a dimension.

Also, you must set a minimum filter of total tracked ads. You may set 'Total Tracked ads' to a specific threshold, or not to include any threshold (-1).

See YouTube Report Type for more information.

YouTube Contextual Suitability Report

{
"reportName": "YouTubeContextualSuitability_Report_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "YOUTUBE_CONTEXTUAL_AGGREGATE",
"fileType": "CSV",
"metrics": [
"Total Eligible Impressions for Contextual Suitability",
"Family & Parenting - Kids Content Impressions",
"Politics Impressions",
"News Impressions",
"Natural Disasters Impressions"
],
"dimensions": [
"Teams",
"Campaigns",
"Date"
]
}

See YouTube Contextual Suitability Report Type for more information.

YouTube Content Level Contextual Suitability Report

{
"reportName": "YouTubeContentLevelContextualSuitability_Report_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "YOUTUBE_CONTEXTUAL_CONTENT",
"fileType": "CSV",
"dimensions": [
"Teams",
"Campaigns",
"Videos",
"Contextual Category",
"Date"
],
"metrics": [
"Impressions"
],
"dimensionFilters": [
{
"fields": [
"Impressions"
],
"operator": "EQUALS",
"values": [
">=100"
]
},
{
"fields": [
"Contextual Suitability Category"
],
"operator": "EQUALS",
"values": [
"Family & Parenting - Kids Content",
"Politics",
"Natural Disasters"
]
}
],
}

You must use the 'Impressions' metric. You must set 'Videos' and 'Contextual Category' as dimensions.

See YouTube Content Level Contextual Suitability Report Type for more information.

Collision Report

{
"reportName": "Collision_Report_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "COLLISIONS",
"fileType": "CSV",
"metrics": [
"Eligible ads for collisions measurement",
"Eligible rate for collisions measurement",
"2 Ad Collisions",
"3 Ad Collisions",
"4+ Ad Collisions",
"Non-Colliding Ads",
"Total Colliding Ads",
"Total Collisions",
"Total Impressions"
],
"dimensions": [
"Teams",
"Media partners",
"Campaigns",
"Colliding Media partners"
],
"dimensionFilters": [
{
"field": "Campaign Status",
"values": [
"Active"
]
},
{
"field": "Include Partner to Partner",
"values": [
"Yes"
]
}
],
"thresholdCondition": {
"metric": "Total Colliding Ads",
"value": -1
}
}

You must set a minimum filter of total tracked ads or total colliding ads (if you use the 'Colliding Media partners' with the 'Include Partner to Partner' filter set to Yes).

See Collision Report Type for more information.

Geo Compliance Report

{
"reportName": "Geo_Compliance_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "GEO_COMPLIANCE",
"fileType": "CSV",
"metrics": [
"Total Tracked Ads"
],
"dimensions": [
"Teams",
"Campaigns",
"Media Partners",
"Placements",
"Date",
"DMA"
],
"thresholdCondition": {
"metric": "Total tracked ads",
"value": -1
}
}

You must set a minimum filter of total tracked ads and you must add a 'DMA', 'State', or 'Country' dimension for a Geo Compliance report.

See Geo Compliance Report Type for more information.

GroupM Fully On Screen Report

{
"reportName": "GroupM_Report_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-16",
"reportType": "GROUP_M",
"fileType": "CSV",
"metrics": [
"Total Impressions",
"% Display Ads Fully on Screen",
"Fully on Screen Display Ads",
"% Videos Fully on Screen",
"Fully on Screen Video Ads",
"GroupM Measured Ads",
"Measured Display Ads",
"Measured Video Ads",
"Total Unblocked Ads",
"Total Billable Ads",
"Viewable Ads",
"TrueView Ads Fully on Screen",
"Measured TrueView Ads Fully on Screen",
"% TrueView Ads Fully on Screen"
],
"dimensions": [
"Teams",
"Placements",
"Campaigns",
"Media partners",
"Device",
"Format",
"Environment",
"Date"
],
"thresholdCondition": {
"metric": "Total Tracked Ads",
"value": -1
}
}

You must set a minimum filter of total tracked ads for a GroupM Fully On Screen report.

See GroupM Fully on Screen Report Type for more information.

Domain Mismatch Report

{
"reportName": "Domain_Mismatch_Example",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2021-03-31",
"reportEnd": "2021-04-06",
"reportType": "DOMAIN_MISMATCH",
"fileType": "CSV",
"metrics": [
"Domain Mismatch Count",
"Domain Mismatch Rate",
"Subdomain Mismatch Count",
"Subdomain Mismatch Rate",
"Total Mismatch Count",
"Total Mismatch Rate",
"Measured Domain Total Tracked Ads"
],
"dimensions": [
"Teams",
"Advertiser",
"Campaigns",
"Measured Domain",
"Bid Domain",
"Mismatch Reason",
"Date"
],
"thresholdCondition": {
"metric": "Measured Domain Total Tracked Ads",
"value": -1
}
"ultimateAdvertiserIds": [2]
}

You must set a minimum filter of 'Measured Domain Total Tracked Ads' for a Domain Mismatch report.

See Domain Mismatch Report Type for more information.

TikTok Report

You must set a minimum filter of "Failed Ads" for the Brand Safety metric (Failed Ads), and "Total Tracked Ads" for Video-Level metrics (Total Tracked Ads, GARM Suitability Category, GARM Floor Category, Risk Level, or Suitability Category) with TikTok Reporting.

TikTok Report Brand Safety

{
"reportName": "TikTok_Reporting",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2022-03-31",
"reportEnd": "2022-04-16",
"metrics": [
"Failed Ads"
],
"dimensions": [
"TikTok Report Type",
"Floor Failures",
"Advertiser",
"Teams",
"Campaigns",
"DSP",
"Date",
"Format",
"Device"
],
"dimensionFilters": [
{
"field": "TikTok Report Type",
"values": [
"reasonElement"
]
}
],
"thresholdCondition": {
"metric": "Failed Ads",
"value": "-1"
}
}

TikTok Report Video-Level

{
"reportName": "TikTok_Reporting",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2022-03-31",
"reportEnd": "2022-04-16",
"reportType": "TIKTOK_REPORTS",
"fileType": "CSV",
"metrics": [
"Total Tracked Ads",
"GARM Suitability Category",
"GARM Floor Category",
"Risk Level",
"Suitability Category"
],
"dimensions": [
"TikTok Report Type",
"Video",
"Advertiser",
"Teams",
"Campaigns",
"Date",
"Format",
"Device"
],
"dimensionFilters": [
{
"field": "TikTok Report Type",
"values": [
"video"
]
}
],
"thresholdCondition": {
"metric": "Total Tracked Ads",
"value": "-1"
}
}

Total Visibility Report

{
"reportName": "TV_Reporting",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2022-03-31",
"reportEnd": "2022-04-16",
"reportType": "TOTAL_VISIBILITY_REPORTING",
"fileType": "CSV",
"metrics": [
"Total Visibility Tracked Ads",
"Total Visibility Tracked Spend (USD)",
"eCPM (USD)",
"qCPM (USD)",
"qCPM delta (USD)",
"Quality Impressions",
"Quality Impressions %",
"Quality Spend %",
"Quality Spend (USD)",
"Unsafe Impressions",
"Unsafe Impressions %",
"Unsafe Spend (USD)",
"Unsafe Spend %",
"Unviewable Impressions (MRC)",
"Unviewable Impressions (MRC) %",
"Unviewable (MRC) Spend (USD)",
"Unviewable (MRC) Spend %",
"Invalid Traffic Impressions",
"Invalid Traffic Impressions %",
"Invalid Traffic Spend (USD)",
"Invalid Traffic Spend %",
"Out of Geo Impressions",
"Out of Geo Impressions %",
"Out of Geo Spend (USD)",
"Out of Geo Spend %"
],
"dimensions": [
"Teams",
"Campaigns",
"DSP",
"DSP Campaign",
"SSP",
"DSP Placement (Line item)",
"DSP Publisher",
"DSP Deal",
"Date",
"Device",
"Format"
],
"dimensionFilters": [
{
"field": "Device",
"values": [
"0",
"1",
"2"
]
}
],
"dateBreakout": "BY_MONTH",
"customMetrics": []
}

Total Visibility reports use IAS data for insights into the supply path and costs.

Attention Report

You may set a minimum filter of total tracked ads for Attention Reporting.

Attention Report Example:

{
"reportName": "Reporting_API_Attention_Reporting",
"reportTeamIds": [
12345,
12346,
12347
],
"reportStart": "2022-03-31",
"reportEnd": "2022-04-16",
"reportType": "ATTENTION_REPORTING",
"fileType": "CSV",
"metrics": [
"Total Tracked Ads",
"Average Ad Density",
"Ad Share of Screen Distribution",
"Eligible Ads for Attention",
"Eligible Impressions For Attention",
"Attention Score",
"Visibility Score",
"Situation Score",
"Interaction Score",
"Subcategory Comparison",
"Pause/Unpause",
"User Scroll",
"Volume Up/Down/Mute"
],
"dimensions": [
"Campaigns",
"Environment",
"Format",
"Device"
],
"dateBreakout": "BY_DAY"
}

Document History

Date

Update

July, 2024

Updates include:

Add YouTube Contextual Suitability Report.

Add YouTube Content Level Contextual Suitability Report.

Add subdomain mismatch metrics to Domain Mismatch Report Type.

April, 2024

Add 'Suitability Category' as a video-level metric for a TikTok Report.

March, 2024

Updates include:

Add Site Quality performance metrics.

Add Attention Report.

July, 2023

Updates include:

Add Total Visibility Report Report.

Update YouTube Report Type to include Google Video Partners.

June, 2023

Add TikTok Report Report.

May, 2023

Add Carbon Emissions and update YouTube Brand Safety and GARM Risk.

October, 2022

Add Domain Mismatch Report Type.

July, 2022

Add GroupM Fully on Screen Report Type.

June, 2022

Updates include:

Add Geo Compliance Report Type.

Add ultimate advertiser ID property.

May, 2022

Updates include:

Add Geo Compliance Report Type.

Add Contextual Segment dimension type to a Performance Report.

Add Keyword and Page/URL dimensions to a Brand Suitability Failure Report.

Update metric names for a Performance Report.

April, 2022

Updates include:

Add attention metrics to a Performance Report.

Fix a typo with custom metrics example.

March, 2022

Updates include:

Add

Collision Report Type. Add Reporting API documentation to Developer Center.

January, 2022

Add

Quality Impressions metrics to a Performance Report.

December, 2021

Update metric names for a

Performance Report.

October, 2021

Add

YouTube Report Type.

September, 2021

Add

Facebook Report Type.

July, 2021

Add

Brand Suitability Failure Report.

May, 2021

Initial documentation of the Reporting API for a Performance Report Type.


Was this article helpful?

Need further help?

Create an IAS case with details of your inquiry to receive help from our internal support team.