Follow the workflow below to gather the necessary data and execute the report with the Generate a report POST operation of Reporting API v2.

Gather data to execute the report

1. Run the List reports operation to get available reports. Reports are categorized by product families and reporting areas. See also Available reports.

2. Get the options of the report you want to execute. The response shows:

   • Available metrics and dimensions. For their descriptions, see the report documentation under Available reports.

   • The default values for metrics, dimensions, time range, and sorting.

   • API limits. For example, the maximum number of dimensions you can use or the maximum number of days from which you can get the data.

   • Available predefined time ranges.

3. You can execute the report with the default values, where available, or specify objects to report on in filters. For example, CP codes.

📘

Some filter values authorize your access to data

Dimensions marked as authorizable: true in the report options authorize your access to data. When filtering by such dimensions, you can only use objects to which you are authorized. For example, only the CP codes to which you have access in ​Control Center​. If you use any other objects, your API call will result in an error.

Form a request body

To generate a report for custom values instead of the default ones, add a request body to your POST request.

1. Decide which metrics and dimensions you want to include in your report and list their names in the metrics and dimensions arrays, respectively.

   • To see which metrics and dimensions are available for your report, get the report options.
   • For the descriptions of metrics and dimensions, see the report documentation under Available reports.

2. Form the filters array of objects to narrow down the report data. See how to use filters.

3. Decide how to sort the data. In the SortBys array, include the name of the metric or dimension by which you want to sort, and the sorting order, ASCENDING or DESCENDING.

4. In the limit field, you can set how many rows of data the API response should return.

JSON request members

Request body example

{
   "dimensions": [
       "url",
       "token",
       "domain",
       "tokenWithVersion"
   ],
   "metrics": [
       "hits",
       "bytes",
       "hits200",
       "bytes200",
       "pristineBytes",
       "averagePristineBytes"
   ],
   "filters": [
       {
           "dimensionName": "cpcode",
           "operator": "IN_LIST",
           "expressions": [
               "909500"
           ]
       },
       {
           "dimensionName": "token",
           "operator": "BEGINS_WITH",
           "expressions": [
               "12345"
           ]
       }
   ],
   "sortBys": [
       {
           "name": "hits200",
           "sortOrder": "DESCENDING"
       }
   ],
   "limit": 1000

Specify query parameters

In your POST request, you can use these query parameters:

Set the report time range

Set the report time range by including query parameters in your POST request. Use one of these methods:

• The start and end parameters with the start and end dates in the ISO-8601 format. Example:

    /reporting-api/v2/reports/{productFamily}/{reportingArea}/{report}/data?start=2023-06-01T00:00:00Z&end=2023-06-04T00:00:00Z
  

• The timeRange parameter with a predefined time range. Each report can support a different set of predefined time ranges. See the report documentation under Available reports for a list of supported time ranges. Example:

    /reporting-api/v2/reports/{productFamily}/{reportingArea}/{report}/data?timeRange=LAST_6_HOURS
  

📘

Use either the timeRange parameter or the start and end parameters. Don’t combine the two methods in one API call.

Enable asynchronous mode

Set the async flag with the true value as a query parameter in your POST request to enable the asynchronous mode. See how to retrieve data asynchronously. Example:

/reporting-api/v2/reports/{productFamily}/{reportingArea}/{report}/data?async=true

Execute the report

Send your POST request to execute the report. As a response, you get the report data as a JSON object.

Get CSV output

To get CSV data instead of JSON, set the Accept header to text/csv, application/problem+json for a CSV output with JSON error messaging.

Integrate with Grafana

You can visualize and observe data from the Reporting API v2 in Grafana. See how to use the Insights Datasource Plugin.

You can get Grafana with the Insights Datasource Plugin already installed through the Cloud Manager's Marketplace.