Reporting API

Version

The following documentation refers to Reporting API v201804.

*Note: The Reporting API is meant to replace the existing Analytics API. The Analytics API is deprecated starting Apr. 26, 2018. This means no further development will be made on the Analytics API. Customers who use the Analytics API should aim to switch over to using the Reporting API as soon as possible.

Overview

Reporting API is a collection of endpoints that opens API access to custom reports created in Report Builder. Customers can extract report files data in CSV (comma-separated values) format from this API This also means that all data fields available in Report Builder are retrievable through the Reporting API.

The API exposes the following endpoints:

  1. Metadata endpoints: allows to query for report details to find the right report to access
  2. Data generation endpoint: allows to generate a new report file containing the most recent data
  3. Data transfer endpoints: allows to download reports file data for a specific report

Metadata endpoints

The metadata endpoints can be used to list all reports and retrieve report details such as row and column selections. It also allows to get a list of all the report files for a specific report. The data format is application/json.

Get Reports

Use this endpoint to list reports.

GET /reports

Get Report

Use this endpoint to get a specific report details.

GET /reports/{reportId}

Get Report Files

Use this endpoint to list report files for a specific report.

GET /reports/{reportId}/files

Get Most Recent Report File

Use this endpoint to get the most recent report file details for a specific report.

GET /reports/{reportId}/files/recent

Get Report File

Use this endpoint to get a specific report file details.

GET /files/{reportFileId}

Data generation endpoint

Generate ad-hoc report

Use this endpoint to generate ad-hoc report file.

POST /reports/{reportId}/files

NOTE: Report files are generated asynchronously. Ensure the report file status is: COMPLETED before fetching the data. To check the report file status use the  GET /files/{reportFileId} endpoint.

Data transfer endpoints

Data transfer endpoints are used to download the actual report file data. The data format is text/csv.

Data Transfer

We use chunked transfer encoding for all successful requests to the data transfer endpoints. It means that we will stream the data in chunks of variable size.

Data Compression

In order to improve transfer speed and bandwidth utilization, client may request compressed content. In order to to this, the additional HTTP request header Accept-Encoding: gzip has to be specified with the HTTP request.

Note: if the HTTP request header Accept-Encoding: gzip has been specified, the HTTP response content is gzip/binary (the Content-Encoding: gzip HTTP response header indicates compressed content) and has to be uncompressed on client side before further processing.

Download Most Recent Report File

Use this endpoint to download the most recent report file of a specific report.

GET /reports/{reportId}/files/recent/data

Download Report File

Use this endpoint to download a specific report file.

GET /files/{reportFileId}/data