Submit a Report Definition

This endpoint submits a report definition and instructs the backend to create the report from the given definition.

Method POST
URL /v2/reports/
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params -
Body Report definition object:
{
    "reportName": "name of report",
    "reportDefinition": {
       "startDateTime": ZoneDateTime,
       "endDateTime": ZoneDateTime,
       "timeGranularity": granularityDefinition,
       "timeColumnIndex": zero-based integer,
       "dimensions": [a, b, c],
       "metrics": [d,e],
       "filters": [filterDefinition1, filterDefinition2]
    }
}

Report name can be up to 255 characters.

Success response

HTTP status: 201 (created)

Header:

Location: a location header is included with the URL of the report, which contains the report's ID.

Body: -

Example

Request header:

POST /v2/reports/ HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/json
x-o-api-key="<your key>"

Request body:

{
  "reportName" : "Monthly Revenue Quarter 4 2016 per Category for Mobile Devices",
  "reportDefinition": {
    "startDateTime": "2016-10-01T00:00:00+02:00",
    "endDateTime": "2016-12-31T23:59:59+02:00",
    "timeGranularity": "month",
    "dimensions": ["category"],
    "metrics": ["revenue"],
    "filters": [
      {
        "type": "in",
        "dimension": "device_container",
        "values" : ["56ca36a7-e350-48e2-a2ad-543d333d96de", "f797c997-d5b2-4a0c-8d53-2bc6vf947ec"]
      }
    ]
  }
}

Success response:

HTTP status:
  201 (Created)

Header:
  Location: https://api.videoplaza.com/v2/reports/f7a550eb-538b-4e23-939b-29b238671d2b

Body: -

Time Filter and Breakdown

Time Filter

Each report must have a specified time range, which is defined by the combination of the startDateTime and endDateTime fields in the request's body. These fields may only contain ISO-8601 formatted date-time strings built up as follows:

  • start with YYYY-MM-DD, indicating year (YYYY), month (MM) and day (DD),
  • followed by a letter T,
  • followed by hh:mm:ss, indicating hour (hh), minutes (mm), and seconds (ss). Indicating seconds is optional.
  • followed by
    • Z to indicate the UTC time zone, or
    • ±hh:mm indicating the offset from UTC in positive or negative direction (±) in hours (hh) and optionally minutes (mm). Make sure to set the offset correctly, otherwise you might lose certain hours of the first and last day of your report due to switching between standard time and daylight savings time.

For example, to define the time range of the first quarter of 2017 in New York, the startDateTime and endDateTime fields could look as follows:

...
"startDateTime": "2017-01-01T05:00:00Z",
"endDateTime": "2017-04-01T04:00:00Z",
...
Note: Dates and times returned in the resulting reports are always according to the time zone defined in your Pulse account.
Note: For static reports, it is recommended to set the end date at least 24 hours in the past from the current time, due to data availability reasons (see Data Availability).

Time Breakdown

You can optionally define a time based breakdown of the data in the report, through the timeGranularity field in the request's body, to show metrics for each year, month, day, or hour. If you set this field to none, or omit it from the body, then the data is not broken down by time.

Time Column Index

You can optionally define the position of the time dimension in the resulting report, through the timeColumnIndex field in the request's body, to further customise the order in which the data is broken down. The value of this field is a zero-based integer, which means that the initial element of a sequence is assigned the index 0. If you omit this field from the body, then the timeColumnIndex takes the value of zero by default, which means that the time dimension is set to first position. Setting this field makes sense only when timeGranularity is different from none.
Note: When defining multiple levels of category breakdown, and setting the timeColumnIndex, the multiple category levels are treated as one dimension, which means the time dimension does not get placed between the different category levels.

Summary

Field Description Supported Values
startDateTime The start date and time for the report in your account's time zone. See Time Filter
endDateTime The end date and time for the report in your account's time zone. The end date and time must be after the start date and time of the report. See Time Filter
timeGranularity The time based breakdown of the report.
  • year
  • month
  • day
  • hour
  • none
timeColumnIndex The position of the time column in the report's results. Setting this field makes sense only when timeGranularity is different from none. Zero-based integer

Supported Dimensions

The order of the dimensions in the report definition controls the order in which the data is broken down in the resulting report. If you have defined a timeGranularity, which is different from none, then defining dimensions becomes optional. However, you must always include the dimensions field to correctly parse the definition. Also see Invalid Combinations.

Basic dimensions

Dimension API naming Description
Device group device_container The device group indicates which devices were targeted by a specific campaign or goal. For example, "Android tablets and phones" could be a device group.
Campaign campaign

The ad's campaign. This dimension is automatically enriched in the report with the campaign's name in a column called campaign_name.

Ad, goal, or campaign dimension cannot be used together with the inventory or fill rate metric in the same report. These combinations do not yield meaningful results.

Goal goal

The ad's goal. This dimension is automatically enriched in the report with the goal's name in a column called goal_name.

Ad, goal, or campaign dimension cannot be used together with the inventory or fill rate metric in the same report. These combinations do not yield meaningful results.

Goal type goal_type The goal's type, like "Impressions", "Click throughs", "Share of Voice (%)", and so on.
Ad ad

The ad. This dimension is automatically enriched in the report with the ad's name in a column called ad_name.

Ad, goal, or campaign dimension cannot be used together with the inventory or fill rate metric in the same report. These combinations do not yield meaningful results.

Format type format_type Ad format type, like "Pre-roll", "Mid-roll", and so on.
Tag tag

Text representing the tags.

Warning:

Tag and audience dimensions cannot be used together in the same report, because the report result cardinality could be too high and surpass the 100000 row limit for Custom Reporting.

Content partner content_partner The content partner targeted by a specific campaign or goal. This dimension is automatically enriched in the report with the content partner's name in a column called content_partner_name.
Advertiser advertiser The advertiser associated with a campaign. This dimension is automatically enriched in the report with the advertiser's name in a column named advertiser_name.
Agency agency The agency associated with a campaign. This dimension is automatically enriched in the report with the advertiser's name in a column named agency_name.
Brand brand The brand associated with a campaign. This dimension is automatically enriched in the report with the advertiser's name in a column named brand_name.
Audience audience

The audience segments on which events were reported. This dimension is automatically enriched in the report with the segment key and value in a column named audience_name and in the following format: <segment key>: <segment value>. For example: Age Group: 18-25.

Warning:

Audience provider filter must always be used in combination with audience dimension and the other way around, otherwise the query fails.

Warning:

Tag and audience dimensions cannot be used together in the same report, because the report result cardinality could be too high and surpass the 100000 row limit for Custom Reporting.

Note: Only create reports on audience if you have an integration with an audience data provider. See Pulse Audience Management (PAM) and Pulse Audience Management for more information.
Custom ad ID custom_ad_id

The custom ID entered for an ad.

Note: The custom ad ID is a free text field, which means that the values may not be unique or even present for each ad.
Custom campaign ID custom_campaign_id

The custom ID entered for a campaign.

Note: The custom campaign ID is a free text field, which means that the values may not be unique or even present for each campaign.
Custom goal ID custom_goal_id

The custom ID entered for a goal.

Note: The custom goal ID is a free text field, which means that the values may not be unique or even present for each goal.
Goal mode goal_mode The mode of a goal, which can be either Normal or Sponsor.
Content ID content_id The ID of the content where ads were served.
Note:

Content IDs are available for reporting in Pulse from March 7, 2018, if you are sending this information to Pulse in your integration(s) through:

  • the content ID parameter in the content metadata object, when using the Pulse SDKs, HTML5 Ad Player or HTML5 Pulse SDK derived plugins, or
  • the content ID parameter, when using direct VAST or VMAP requests.
Flag adserving_flags The flags used in Pulse to mark and remove monetisation from specific content items. Specified by the f request parameter in an ad request to Pulse.

Geography dimensions

Currently, codes are used to lookup regional data. The codes are automatically enriched with names in the resulting report.

Dimension API naming Description
Country country Country code
Region region Region code
City city City code
Metro Area metro_area Metro Area code

Category dimension

API Naming: category

Breakdown of data based on category is limited to:
  • five levels in the category tree, where the first level corresponds to the category selected in the filter or the root category of your account, in case it is not set in the filter.
  • maximum the seventh level of the category tree, counting the root category as the first level.
So, if you select a level 4 category in your filter, and set the category dimension breakdown to 5 levels, the report only breaks down the data up to 3 more levels.

For example, if this is the category tree for your account:

  • Root Category (UUID=1)
    • Sports (UUID=11)
      • Football (UUID=111)
        • UEFA Champions League (UUID=1111)
        • FIFA World Cup (UUID=1112)
      • Tennis (UUID=112)
      • Basketball (UUID=113)
    • Kids TV (UUID=12)
    • Reality shows (UUID=13)
    • Hobbies (UUID=14)
      • Cooking (UUID=141)
      • Fashion (UUID=142)
    • News (UUID=15)
    • Documentaries (UUID=16)
      • Nature (UUID=161)
      • Technology (UUID=162)
      • History (UUID=163)

, and you selected to filter on 'Sports', and set Category as a dimension with level two, then the breakdown looks as follows:

Dimensions Metrics
Category Category X
Sports Direct count for metric X for Sports Category (not including counts for child categories).
Football Total count for metric X for Football category and all its child categories, which are UEFA Champions League and FIFA World Cup.
Tennis Direct count for metric X for Tennis category.
Basketball Direct count for metric X for Basketball category.

To define multiple levels of category breakdown, you simply need to repeat category up to the amount of levels required, and not exceeding five times, in the dimensions object. For example, to break down into three levels:

...
"reportDefinition": {
    "dimensions": ["category","category","category"],
...
Note: When defining multiple levels of category breakdown, and setting the timeColumnIndex, the multiple category levels are treated as one dimension, which means the time dimension does not get placed between the different category levels.

The category dimension is automatically enriched in the report with the category's name.

Error tracking dimension

Note:
Error tracking reports only work if error tracking is enabled for your account, and you have an integration with at least one of the following SDKs:
  • HTML5 SDK (Core and Pulse) or any of its derivatives (HTML5 Ad Player and Plugins) for version 2.1.16.23.1 or higher
  • iOS Pulse SDK version 2.3.17.1.0 or higher
  • Android Pulse SDK version 2.3.16.25.0 or higher

No error tracking information is available for direct VAST or VMAP integrations.

Warning: Error tracking as a dimension only yields meaningful reports when used in conjunction with error tracking as a metric (error).

API Naming: error_code

Retrieve the counts for the different errors that have occurred. This dimension is automatically enriched in the report with the error code's name in a column called error_code_name. For more information and a list of all possible error codes and their descriptions, see Pulse Error Tracking.

Supported Metrics

The order of the metrics in the report definition controls the order in which the data is presented in the resulting report. Also see Invalid Combinations. You can generate reports for the following metrics:

Metric API naming Description
Inventory inventory

The amount of opportunities to show an ad.

Ad, goal, or campaign dimension cannot be used together with the inventory or fill rate metric in the same report. These combinations do not yield meaningful results.

Requesting inventory metrics only yields meaningful results for the following dimensions, because they are part of the ad request (directly or indirectly):
  • Device group
  • Format type
  • Tag
  • Content partner
  • Geography dimensions
  • Category
Impressions impression The amount of successfully shown ads. Success is reported as soon as the first frame of the ad is shown.
Revenue revenue The amount of revenue.
Unique Impressions unique_impressions The amount of successfully shown ads to unique viewers, meaning that a viewer who has seen the ad more than once is only counted one time.
Unique inventory unique_inventory The amount of opportunities to show an ad to unique viewers.
Click-throughs click_through The amount of times a click-through link was activated.
Click-through rate ctr The proportionate amount of times a click-through link was activated (=click-throughs/times a click-through is available).
Close close The amount of times the viewer closed an ad.
Companion Impressions companion_impression The amount of times a companion banner associated with a linear ad was successfully shown to the viewer.
Companion Click-throughs companion_click_through The amount of times a companion banner associated with a linear ad was clicked by a viewer.
Completion rate completion_rate The amount of times an ad was viewed to completion in comparison to the amount of times an ad was started (=Ad Completed/ Impressions).
Content Start content_start The amount of times that video content was started.
Fill rate fill_rate The amount of impressions in comparison to the amount of inventory (=Impression/Inventory).

Ad, goal, or campaign dimension cannot be used together with the inventory or fill rate metric in the same report. These combinations do not yield meaningful results.

Interaction interaction The amount of times that the viewer interacted in a way with an ad.
Interaction Rate interaction_rate The amount of interactions in comparison to the amount of impressions.
Ad started ad_started The amount of time an ad was started, which is the same as impression count for Pulse.
Ad 25 % ad_25_percent_completed The amount of times an ad was viewed to at least 25% completion.
Ad 50 % ad_50_percent_completed The amount of times an ad was viewed to at least 50% completion.
Ad 75 % ad_75_percent_completed The amount of times an ad was viewed to at least 75% completion.
Ad completed ad_completed The amount of times an ad was viewed to completion.
Average view-through rate view_rate A complex calculation based on quartile view-through rates in comparison to the amount of impressions. This calculation is explained in the following article: How is view-through rate calculated in Custom Reporting?
Error error

The amount of times errors or a specific error occurred.

To create meaningful reports, you must always use the Error Code dimension in combination with the Error metric. You can also report on error counts for the following dimensions:
  • Campaign
  • Goal
  • Ad
  • Device Group
  • Geography (Country, Region, City and Metro Area)
  • Format Type
  • Category
  • Tag
Skip skip The amount of times an ad was skipped by the viewer.

Supported Filters

One type of filter is currently supported. The in filter takes an array of values and works similarly to the SQL operator in.

Multiple filters work in addition to one another, which means that filters are strung together with the AND operator.

Requirements and constraints
  • Values field of in filter type must contain at least one value.
  • Maximum of one category filter can be specified.
  • If category filter is present, it must have exactly one filter value.
  • Category filter value must be a UUID.
  • Maximum depth of selected category from the root level is seven, where root level is counted as level one.
  • filters field must be present in the body, but may be empty. For example: "filters": []
  • Country, region, and city filters require you to provide the codes for the required geographies. To get these codes, use the Geography API. The swagger documentation for this service is located at: Geography API
  • If audience provider filter is present, it must have exactly one filter value. Also see Invalid Combinations.
Filter API naming Description
Device group device_container

The device group indicates which devices were targeted by a specific campaign or goal. For example, "Android tablets and phones" could be a device group.

When using this filter, you must provide the ID(s) of the device group(s).

Campaign campaign

The ad campaign(s) you want to filter on.

When using this filter, you must provide the ID(s) of the campaign(s).

Goal goal

The ad goal(s) you want to filter on.

When using this filter, you must provide the ID(s) of the goal(s).

Goal type goal_type

The goal type(s) you want to filter on, values are case sensitive:

Note: Not all of the values below may be applicable to your account. You should only ever filter on goal types that are available to you.
  • impression: Impressions goal
  • shareOfVoice: Share of Voice (%) goal
  • unlimitedImpression: Unlimited impressions goal
  • firstQuartile: 25% Ad Completion goal
  • secondQuartile: 50% Ad Completion goal
  • thirdQuartile: 75% Ad Completion goal
  • complete: 100% Ad Completion goal
  • clickThrough: Click throughs goal
  • realTimeBidding: Priority unreserved goal
Ad ad

The ad(s) you want to filter on.

When using this filter, you must provide the ID(s) of the ad(s).

Format type format_type

Ad format type, values are case sensitive:

Note: Not all of the values below may be applicable to your account. You should only ever filter on format types that are available to you.
  • Preroll
  • Midroll
  • Postroll
  • PauseAd
  • SeekRoll
  • Overlay
  • Companion
  • Skin
Tag tag
Note: You may filter on maximum ten tags in one report. Using more tags may result in failing reports.

The filter in-value contains a comma separated list of strings representing the full textual tags included in the filter:

{
"type": "in",
"dimension": "tag",
"values":["tag1", "tag2"]
}

Tags are not case sensitive.

Content partner content_partner

The content partner targeted by a specific campaign or goal.

When using this filter, you must provide the ID(s) of the content partner(s).

Advertiser advertiser

The advertiser associated with a campaign.

When using this filter, you must provide the ID(s) of the advertiser(s).

Agency agency

The agency associated with a campaign.

When using this filter, you must provide the ID(s) of the agency(ies).

Brand brand

The brand associated with a campaign.

When using this filter, you must provide the ID(s) of the brand(s).

Country country Country code. Use the Geography API to get the codes.
Region region Region code. Use the Geography API to get the codes.
City city City code. Use the Geography API to get the codes.
Metro Area metro_area Metro Area code. Use the Geography API to get the codes.
Category category

You can filter on only one category that is up to seven levels deep in the category tree, counting the root category as level one. All child categories of the selected category are automatically included. When using this filter, you must provide the UUID of the category.

Error Code error_code Filter on specific error codes, which are described in Pulse Error Tracking.
Audience Provider audience

You can filter on only one audience provider. When using this filter, you must provide the UUID of the audience provider. To get these values for the audience providers you have an integration with, use the Audience API.

Warning:

Audience provider filter must always be used in combination with audience dimension and the other way around, otherwise the query fails.

Note: Only create reports on audience if you have an integration with an audience data provider. See Pulse Audience Management (PAM) and Pulse Audience Management for more information.
Custom ad ID custom_ad_id Filter ads in the results based on their custom ad IDs.
Custom campaign ID custom_campaign_id Filter campaigns in the results based on their custom campaign IDs.
Custom goal ID custom_goal_id Filter goals in the results based on their custom goal IDs.
Goal Mode goal_mode Filter goals in the results based on their goal mode, which can be either Normal or Sponsor.
Content ID content_id Filter the content you served ads for based on the content's recorded ID.
Note:

Content IDs are available for reporting in Pulse from March 7, 2018, if you are sending this information to Pulse in your integration(s) through:

  • the content ID parameter in the content metadata object, when using the Pulse SDKs, HTML5 Ad Player or HTML5 Pulse SDK derived plugins, or
  • the content ID parameter, when using direct VAST or VMAP requests.
Flag adserving_flags The flag(s) you want to filter on, values are case sensitive:
  • NoCommercials
  • NoPrerolls
  • NoMidrolls
  • NoPostrolls
  • NoOverlays
  • NoFlagsSet