API

Use filters

You can narrow down the report data by adding the filters array to your POST request body.

📘

Supported filters are report-specific

API v2 lets you filter by both dimensions and metrics, but each report can have its own set of supported filters. For example, it can support filtering by dimensions only. Check the report documentation under Available reports to see which filters you can use.

  1. Run the GET report options operation for more information on available filters. If a dimension or a metric is labeled as filterable: true, you can filter by it. If a dimension or a filter is labeled as mandatory: true, you have to use it as a filter. The report options also show the filter type, TEXT or ENUM, and, in case of ENUM filters, available filter values. Example:
{
    "name": "responseClass",
    "type": "STRING",
    "filterable": true,
    "mandatory": false,
    "filterType": "ENUM",
    "filterEnumValues": [
        "0xx",
        "1xx",
        "2xx",
        "3xx",
        "4xx",
        "5xx",
        "6xx"
      ],
    "authorizable": false
}

  1. Add each filter as an object to the filters array in the POST request body.

    • To filter by a dimension, include:
FieldTypeDescription
dimensionNameStringName of the dimension for which you want to filter. For example, cpcode.
operatorStringThe filtering logic. One of:


  • MATCH_REGEXP. Shows values that match the specified regular expression. This option has the same behavior as the rlike function from Spark SQL.
  • NOT_MATCH_REGEXP. Shows values that don't match the specified regular expression. This option has the same behavior as the rlike function from Spark SQL.
  • BEGINS_WITH. Shows values that start with the specified string.
  • NOT_BEGINS_WITH. Shows values that don't start with the specified string.
  • ENDS_WITH. Shows values that end with the specified string.
  • NOT_ENDS_WITH. Shows values that don't end with the specified string.
  • CONTAINS. Shows values that contain the specified string.
  • NOT_CONTAINS. Shows values that don't contain the specified string.
  • EXACT. Shows values that exactly match the specified string.
  • IN_LIST. Shows values that are present on the specified list.
  • NOT_IN_LIST. Shows values that are not present on the specified list.

For authorizable filters and filters of the ENUM type, you can only use the IN_LIST and NOT_IN_LIST operators.
expressionsArray of stringsFilter values. If the filter type is ENUM, the report options show available values you can use.

  • To filter by a metric, include:
FieldTypeDescription
metricNameStringName of the metric for which you want to filter. For example, edgeHitsSum.
operatorStringThe filtering logic. One of:


  • EQUAL. Shows values that are equal to the specified value.
  • NOT_EQUAL. Shows values that aren't equal to the specified value.
  • LESS_THAN. Shows values that are less than the specified value.
  • GREATER_THAN. Shows values that are greater than the specified value.

expressionString or numberFilter value.

To filter by a metric, you need to include it in the metrics array in the request body.

  • Example: 
      "filters": [
     {
      "dimensionName": "cpcode",
       "operator": "IN_LIST",
       "expressions": [
         "1849",
         "2084",
         "2577",
         "3004"
         ]
     },
     {
       "metricName": "edgeHitsSum",
       "operator": "GREATER_THAN",
       "expression": "1"
     }
   ]

📘

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.