# 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.

:::note
To retrieve this data, you must be subscribed to Azion Bot Manager and use the [GraphQL API](/en/documentation/devtools/graphql-api/overview/). Contact the [Sales team](https://www.azion.com/en/contact/) for more details on the subscription.
:::

---

## Querying data

To query your data, proceed as follows:

1. Access the GraphiQL Playground at the following link: `https://api.azion.com/v4/metrics/graphql`.
    - You must be logged in to your Azion account. Otherwise, you'll receive an error message.
2. Send a query following this format:

```graphql
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` |

:::note
This example retrieves data for `action`, `botCategory`, `botMode`, `classified`, and the total (`sum`) of requests identified as bots during the specified time range, grouped by the selected fields. To know more about the available fields, check the [Real-Time Metrics GraphQL API Fields documentation](/en/documentation/devtools/graphql-api/features/gql-real-time-metrics-fields/).
:::

3. You'll receive a JSON response similar to this: 

```json
{
  "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 |

:::tip
To know more about the available fields, check the [Real-Time Metrics GraphQL API Fields documentation](/en/documentation/devtools/graphql-api/features/gql-real-time-metrics-fields/).
:::