Submit report definition

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

Method POST
URL https://api.videoplaza.com/v2/reports/
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params -
Body Report definition object:
{
    "reportName": "string",
    "reportDefinition": {
       "startDateTime": "ISO-8601 formatted date-time string",
       "endDateTime": "ISO-8601 formatted date-time string",
       "timeGranularity": "none|year|month|day|hour",
       "timeColumnIndex": zero-based integer,
       "dimensions": [
         "string", 
         "string",
         {
          "type": "audienceSegmentation",
          "providerId": "string",
          "segmentationId": integer
         }
       ],
       "metrics": [
         "string", 
         "string"
       ],
       "filters": [
         {
          "type": "in",
          "dimension": "string",
          "values": [
            "string", 
            "string"
          ]
         },
         {
          "type": "audienceSegment",
          "dimension": "audience_segment",
          "values": [
            "segmentationId-segmentId", 
            "segmentationId-segmentId"
          ],
          "providerId": "string" 
         }
      ]
   }
}
Only timeGranularity and timeColumnIndex are optional fields. All other fields are required. In addition:
  • Report name can be up to 255 characters.
  • You can pass in a maximum of eight dimensions in a report definition.
  • You can pass in only one in filter and only one audienceSegment filter.
  • You must pass in the filters and dimensions field, but these may be empty. For example: "filters": [] and "dimensions": [].
  • You must pass in the metrics field and it must have at least one value.
Success response

HTTP status: 201 (created)

Header:

Location: a location header is included with the URL of the report, which contains the report 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 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 Required. The start date and time for the report in your account time zone. See Time Filter
endDateTime Required. The end date and time for the report in your account time zone. The end date and time must be after the start date and time of the report. See Time Filter
timeGranularity Optional. The time based breakdown of the report.
  • year
  • month
  • day
  • hour
  • none
timeColumnIndex Optional. The position of the time column in the report results. Setting this field makes sense only when timeGranularity is different from none. Zero-based integer

Supported dimensions

dimensions field must be present in the body, but may be empty. For example: "dimensions": []. You can pass in a maximum of eight dimensions in a report definition.

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, 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 campaign. This dimension is automatically enriched in the report with the campaign name in a column called campaign_name. Also see Invalid combinations.
Goal goal The goal. This dimension is automatically enriched in the report with the goal name in a column called goal_name. Also see Invalid combinations.
Goal type goal_type The goal 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 name in a column called ad_name. Also see Invalid combinations.
Format type format_type Ad format type, like "Pre-roll", "Mid-roll", and so on.
Tag tag

Text representing the tags. Also see Invalid combinations.

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 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 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 agency 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 brand name in a column named brand_name.
Audience (legacy) audience

(Legacy) The audience segments on which events were reported. This dimension is automatically enriched in the report with the key and value in a column named audience_name and in the following format: segmentation key label (segmentation name): segmentation value label (segment name). For example: Age: 18-25. Also see Invalid combinations.

Any missing mappings resolve to segmentation key label (segmentation name): undefined in your reports, for example Age: undefined.

Note: Only create reports on audience if you have an integration with an audience data provider. See 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 integrations 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.
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, 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)

If you selected to filter on 'Sports', and set Category as a dimension with level two, 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 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 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 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.

Complex dimensions

Currently, only audience segmentation is supported as a complex dimension and you can pass in only one complex dimension of "type": "audienceSegmentation". Also see Invalid combinations.

Break down the data based on segments from a specific audience segmentation belonging to the specified audience data provider.

{
 "type": "audienceSegmentation", 
 "providerId": "string",  
 "segmentationId": integer
}

All fields are required. Use the Audience Management API to retrieve the providerId and segmentationId.

When using both the audienceSegment filter and the audienceSegmentation complex dimension in one report, you can break down the data by segments from a segmentation that is different than the one you filtered on, but it must belong to the same audience provider.

You might find the following segment values in your segmentation breakdowns:
  • undefined - 'SegmentationId-SegmentId' not found, for example undefined ´1-0´not found: this means you passed in an unknown segment in the ad request and Pulse recorded events for it (segmentId=0 in our example). You should make sure you are passing in correct values in your ad requests. This does not occur if you filter and breakdown on the same segmentation.
  • undefined - Missing value: this means events were recorded, but are not associated with the requested segmentation dimension. For example, you are breaking down today's data by gender, and there are events on male and female segments, but there are also events that are not associated with the gender segmentation. This does not occur if you filter and breakdown on the same segmentation.
Note: Only create reports on audience if you have an integration with an audience data provider. See Pulse Audience Management for more information.

Supported metrics

The metrics field is required and must have at least one value. 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.

Requesting inventory metrics only yields meaningful results for the following dimensions, because they are part of the ad request (directly or indirectly):
  • Audience (legacy)
  • Audience segmentation
  • Category
  • Content ID
  • Content partner
  • Device group
  • Flag
  • Format type
  • Geography dimensions
  • Tag

Also see Invalid combinations.

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). Also see Invalid combinations.
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 should 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

filters field must be present in the body, but may be empty. For example: "filters": []

Currently, only two types of filters are supported: in and audienceSegment.

in filter

{
 "type": "in",
 "dimension": "string",
 "values": ["string", "string"]
 }

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.
  • 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 IDs of the device groups.

Campaign campaign

The campaigns you want to filter on.

When using this filter, you must provide the IDs of the campaigns.

Goal goal

The goals you want to filter on.

When using this filter, you must provide the IDs of the goals.

Goal type goal_type

The goal types 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 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 ads you want to filter on.

When using this filter, you must provide the IDs of the ads.

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 filter on format types that are available to you.
  • Preroll
  • Midroll
  • Postroll
  • PauseAd
  • SeekRoll
  • Overlay
  • Companion
  • Skin
Tag tag
Note: You should 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 IDs of the content partners.

Advertiser advertiser

The advertiser associated with a campaign.

When using this filter, you must provide the IDs of the advertisers.

Agency agency

The agency associated with a campaign.

When using this filter, you must provide the IDs of the agencies.

Brand brand

The brand associated with a campaign.

When using this filter, you must provide the IDs of the brands.

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 (legacy) audience

(Legacy) 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 Management API.

Also see Invalid combinations.

Note: Only create reports on audience if you have an integration with an audience data provider. See 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 recorded content ID.
Note:

Content IDs are available for reporting in Pulse from March 7, 2018, if you are sending this information to Pulse in your integrations 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 you want to filter on, values are case sensitive:
  • NoCommercials
  • NoPrerolls
  • NoMidrolls
  • NoPostrolls
  • NoOverlays
  • NoFlagsSet

audienceSegment filter

The audienceSegment filter takes an array of values and allows you to filter based on specific segments in an audience segmentation for the audience provider you have an integration with.

{
 "type": "audienceSegment",
 "dimension": "audience_segment",
 "values": [        
    "segmentationId-segmentId", 
    "segmentationId-segmentId"
 ],  
 "providerId": "string"
}

All fields are required. Use the Audience Management API to retrieve the segmentationId, segmentId, and providerId.

Requirements and constraints
Note: Only create reports on audience if you have an integration with an audience data provider. See Pulse Audience Management for more information.
  • Values field of audienceSegment filter type must contain at least one value.
  • All values must belong to the same segmentation from the specified audience data provider, which means they must have the same segmentationId.
  • When using both the audienceSegment filter and the audienceSegmentation complex dimension in one report, you can break down the data by segments from a segmentation that is different than the one you filtered on, but it must belong to the same audience provider.
  • See Invalid combinations for more information.