API

Execute the report

The API provides two operations that allow you to execute reports in slightly different ways:

  • The Generate a report POST operation accepts a request with a query JSON object that specifies the report's criteria.

  • The Get a report GET operation specifies the same data using query parameters. Note that overly long URLs may fail to execute, in which case use you can run the POST operation instead.

Both POST and GET operations respond with the same report object.

To run the Generate a report POST operation:

  1. Prepare a query object for the POST request.

  2. Specify the list of CP codes as an objectIds array, otherwise set objectIds to a string value of all. Set the accompanying objectType to cpcode.

  3. Optionally specify an array of metrics whose name values you gathered earlier. Otherwise omit metrics from the request to include all available metrics for this report.

  4. Optionally specify a map of filters whose name values you gathered earlier. Otherwise omit filters from the request to generate unfiltered data.

  5. POST the object to /reporting-api.

To run the Get a report GET operation:

  1. Specify an objectType query parameter of cpcode.

  2. Specify an objectIds query parameter with the set of CP codes you want to report on, separated with commas. Otherwise instead you can specify an allObjectIds query parameter to widen the scope of the report. Doing so may also shorten the URL.

  3. Specify a metrics query parameter, with the set of metric name values you gathered earlier, separated with commas.

  4. Specify a filters query parameter, with the set of filter name values you gathered earlier, followed by = and the corresponding value. Separate each name/value pair with commas. To represent more than one value, repeat the filter name. For example, this is how filters would appear prior to URL-encoding: filters=ip_version=ipv4,ip_version=ipv6,traffic_type=standard_secure.

To get CSV data instead of JSON:

  • When making either the POST or GET request described above, set the Accept header to text/csv, application/problem+json for CSV output with JSON error messaging.

📘

The use of negative filters

Depending on the report type, negative filters, such as url_not_start_with or url_not_contain, work in a different way. For certain reports, these filters use the OR logic, which means you can only use one filter value at a time. Otherwise, the filters may not work in the expected way. If this is the case, you can see this information in the report definition in Available reports.