How to query Bot Manager data with GraphQL API

The botManagerMetrics dataset provides access to real-time aggregated data from Azion Bot Manager activity, related to bot traffic, actions, and behavior across your applications. This dataset is part of the Real-Time Metrics GraphQL API and is generated from the requests analyzed and identified as bots, whether they’re good or bad, or legitimate traffic.

This information can be accessed through the GraphQL API. Additionally, this data is retained and available for up to 2 years.

This guide will explain how to query Bot Manager data using the GraphiQL playground.

Querying data

To query your data, proceed as follows:

Access the GraphiQL playground going to the following link: https://manager.azion.com/metrics/graphql.
- You must be logged in to your Azion account. Otherwise, you’ll receive an error message.
Send a query following this format:

query {
  botManagerMetrics(
    filter: {
      tsRange: {
        begin: "2024-09-23T15:00:00"
        end: "2024-09-23T17:00:00"
      }
    }
    aggregate: {
      sum: requests
    }
    orderBy: [ts_ASC]
    groupBy: [ts, action, botCategory, botMode, classified]
    limit: 10000
  ) {
    action
    botCategory
    botMode,
    classified
    sum
  }
}

Where:

Field	Description
`filter`	Defines the criteria used to filter the data returned by the query
`tsRange`	A subfield of `filter`. Specifies a time range for filtering data. It includes `begin` and `end` fields to define the start and end timestamps. Format: `"YYYY-MM-DDTHH:mm:ss"`; example: `"2024-04-11T00:00:00"`
`sum: requests`	Returns the total number of requests evaluated within the specified time range, after applying any filters
`orderBy`	Specifies the order in which the results should be returned. Examples: `[ts_DESC]`, for descending order, and `[ts_ASC]`, for ascending order
`groupBy`	Specifies the fields by which the query results should be grouped. Example: `[ts]`
`limit`	Specifies the maximum number of results to return. System maximum: `10000`

You’ll receive a JSON response similar to this:

{
  "data": {
    "botManagerMetrics": [
      {
        "action": "allow",
        "botCategory": "Enterprise Bot",
        "botMode": "web",
        "classified": "good bot",
        "sum": 6
      },
      {
        "action": "allow",
        "botCategory": "Brute Force",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 325
      },
      {
        "action": "allow",
        "botCategory": "Bad Bot Signatures",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 68
      },
      {
        "action": "allow",
        "botCategory": "Non-Bot Like",
        "botMode": "web",
        "classified": "legitimate",
        "sum": 34359
      },
      {
        "action": "redirect",
        "botCategory": "Bad Bot Signatures",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 703
      },
      {
        "action": "allow",
        "botCategory": "Monitoring Bot",
        "botMode": "web",
        "classified": "good bot",
        "sum": 8
      },
      {
        "action": "allow",
        "botCategory": "Bad Bot Signatures",
        "botMode": "web",
        "classified": "under evaluation",
        "sum": 2902
      },
      {
        "action": "redirect",
        "botCategory": "Malicious Browser Behavior",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 17
      },
      {
        "action": "allow",
        "botCategory": "Scripted Bots",
        "botMode": "web",
        "classified": "bad bot",
        "sum": 1
      }
    ]
  }
}

Where:

Field	Description
`action`	Action performed by Azion Bot Manager for accesses identified as bots
`botCategory`	Bot category identified in the request. Example: `scraping`, `crawling`, `brute-force`
`botMode`	Bot protection mode used in the request. Example: `Web`
`classified`	Traffic identification, being `bad bot`, `good bot`, `legitimate`, or `under evaluation` the possible values
`sum`	Total number of requests for each specific combination of attributes. Each object in the response groups the requests based on these attributes