Custom Reporting API

The Custom Reporting API offers a powerful tool to pull complex reports from Pulse, within limits. The Custom Reporting API allows you to generate reports as you need them, without having pre-existing report definitions. This means that:

  • You create report definitions from scratch for each new report, stating the metrics, dimensions, and filters you want.
  • Reports can be generated for unaggregated data.
  • Reports may be slower to generate because data needs to be aggregated each time you generate a new report.

Getting started

  • Base URL: https://api.videoplaza.com/v2/reports
  • Requests: GET, POST, and DELETE requests are used. You pass parameters by using common REST parameters like PATH and QUERY, as well as HTTP HEADERS. The body of the requests should be provided in JSON format and encoded using UTF-8.
  • Responses: All responses contain an HTTP status code in the header and the body is in JSON format, except for fetching the generated report.
  • Swagger documentation: Custom Reporting API
  • Related user documentation:

Data availability

Tracking data is received continuously in the Pulse backend, and is sorted into hour-long buckets according to the tracking request's timestamp from when the request was triggered on the end user's device. Because this data may be received a lot later than the time it was sent, we employ two processing windows:
  • one that processes data from the bucket with timestamps from three hours to two hours ago, and
  • one that simultaneously processes data from the bucket with timestamps from 25 hours to 24 hours ago.

One processing run takes about 30 minutes, and with the double processing of each bucket, a 99.99% of data completeness level is reached in most circumstances. However, if significant amounts of data is received after 24 hours, or inconsistencies are detected, the data can be reprocessed manually.

Limitations

The following limitations apply to the Custom Reporting API:
  • Data for Custom Reporting is only available for the past 25 months. Reports where at least a part of the selected time span falls outside the data retention period, fail to run.
    Note:

    In addition,

    • audience data is only available from December 1, 2017
    • content ID data is only available from March 7, 2018
    • meaningful flag data is only available from November 19, 2018
  • Revenue metrics are visible to all users of your Pulse account when using Custom Reporting, even if a particular user cannot see revenue metrics in the Pulse User Interface.
  • The time span of a report can be maximum twelve months. Reports requested over a longer period fail to run.
  • You can run maximum two reports at the same time. If there are two reports waiting to complete in Custom Reporting, you can still create new reports but their status is set to "Queued".
    • When one of the currently running reports is done (ready, failed, or cancelled), the first report in queue is run.
    • Queued reports are ordered based on creation or refresh date and time, so the report with the oldest creation or refresh date and time is the first one in queue, and this order cannot be changed.
    • You can queue maximum 10 reports. Refreshing a report also counts towards your queue.
    • You can delete or cancel queued reports.
  • The query for a report runs for maximum 1 hour. Queries that take longer are cancelled, and the report's status is set to 'Failed'.
  • There is a daily quota of 300 reports you can run using the Custom Reporting UI and API combined. For more information, contact your Account Manager.
  • Only the described dimensions, metrics, and filters in this document set are available in Custom Reporting.
  • You can define maximum eight grouping dimensions for a report.
  • Only 200 reports are loaded and visible in the user interface.
  • Reports return maximum 100,000 rows. To make sure your report is not incomplete due to reaching the maximum number of rows, see these tips.
  • You are recommended to filter on maximum ten tags in a report. Although more tags are allowed, we cannot guarantee a successful run of the report.
  • If the refreshable reports functionality is enabled for your account, and a report was created with a future end date, then it can be refreshed at the earliest six hours after the last time it was refreshed or created for the first time successfully. Also, you are only able to refresh the report results up until three days after that future date has passed.
  • The Custom Reporting tool calculates the approximate count of unique inventory and unique impressions metrics by using the HyperLogLog algorithm, which provides deterministic results when running reports for the same time range, filters, and dimensions. This way your reports run faster, and finish, which cannot be guaranteed when using distinct counts. The expected difference from distinct counts is only 2 to 3%. For more information, see Using HLL++ to speed up count-distinct in massive datasets. Also see Why is there a discrepancy in unique impression data between Custom Reporting and Performance Metrics Explorer?
  • 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.

  • Resolving audience segments to names depends on a mapping entered in Pulse backend, where no history is recorded. This means that the names in your reports may change if updates were made to the mapping. Any missing mappings resolve to undefined in your reports.
  • When using the new audience segment filter, you can only filter for segments within one segmentation. However, when using both the audience segment filter and the audience segmentation 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.

Invalid combinations

Before you begin, you should understand which filters, dimensions, and metrics cannot be used together in the same report, and which depend on a specific combination.
  • The inventory or fill rate metric cannot be used together with these dimensions in the same report:
    • Ad
    • Agency
    • Brand
    • Campaign
    • Custom ad ID
    • Custom campaign ID
    • Custom goal ID
    • Goal
    • Goal mode
    • Goal type

    These combinations do not yield meaningful results.

  • Tag dimension cannot be combined with the legacy audience dimension or new audience segmentation dimension in the same report, because the report result cardinality could be too high and surpass the 100,000 row limit for Custom Reporting.

  • The legacy audience provider filter must always be used in combination with the legacy audience dimension and the other way around.

  • When using the legacy audience provider filter, you are only allowed to select one audience provider for filtering. You cannot combine two different audience data providers in one report.

  • The new audience segment filter and new audience segmentation dimension cannot be used in combination with the legacy audience provider filter and legacy audience dimension.

  • When using both the audience segment filter and the audience segmentation dimension in one report, they must belong to the same audience provider. You cannot combine two different audience data providers in one report.

If the above is not respected, you cannot create the report and you get a 422 error from the Custom Reporting API.