Query Bot Manager data with GraphQL
Read the classification counts Bot Manager produced, with one query against the botManagerMetrics dataset in the GraphiQL Playground.
You read the classification counts of your bot traffic from the botManagerMetrics dataset, in the GraphiQL Playground or from any GraphQL client that sends your credentials.
botManagerMetrics aggregates the requests Bot Manager analyzed, whether it identified them as bots or as legitimate traffic, and groups them by the action, the category, the mode, and the verdict of each one. The dataset is retained for 2 years, so a time range can reach that far back.
It carries counts, not requests. There is no score field on it, because a score belongs to a single request and is written on the report log line, which Logs documents. The second Bot Manager dataset, botManagerBreakdownMetrics, carries the URLs bot traffic reached and the addresses it came from, and it is retained for 60 days. For more information, refer to Query the top URLs bots reach with GraphQL.
Prerequisites
- A subscription to Bot Manager on your account. The dataset is not retrievable without one.
- A signed-in Azion session in the browser you open the Playground from. A request that carries no session returns an error message.
- Access to the GraphiQL Playground.
- A personal token, to send the query from a GraphQL client instead. The call then carries the
Authorization: Token [TOKEN VALUE]header. For more information, refer to Personal Tokens.
Query the classification counts
The query filters the dataset by a time range, sums requests per group, and returns one object per combination of the grouped fields. To run it:
Go to https://api.azion.com/v4/metrics/graphql.
Set begin and end to the period you want to read:
The response carries one object per combination of the grouped fields, with the summed requests in sum:
You now have the requests Bot Manager analyzed in the period, counted by how it classified each one and by the action it applied.
Query fields
| Field | What it carries |
|---|---|
filter | The criteria that narrow the returned data |
tsRange | A subfield of filter, with a begin and an end timestamp in the format YYYY-MM-DDTHH:mm:ss. For example: 2024-04-11T00:00:00 |
aggregate | With sum: requests, the total requests evaluated in the range, after the filters apply |
groupBy | The fields the results are grouped by. Every combination of their values becomes one object in the response |
orderBy | The order of the results. [ts_ASC] returns them ascending, [ts_DESC] descending |
limit | The maximum number of results the response carries |
Response fields
| Field | What it carries |
|---|---|
action | The action Bot Manager applied to the requests in the group. For example: redirect |
botCategory | The bot category identified in the request. For example: Brute Force |
botMode | The bot protection mode used in the request. For example: web |
classified | How the traffic was identified: bad bot, good bot, legitimate, or under evaluation |
sum | The requests behind that combination of grouped fields. For example: 34359 |
classified and botCategory are independent of each other. One category, such as Bad Bot Signatures, can hold requests classified under evaluation alongside requests classified bad bot.
The query selects five fields, and the dataset carries more, including the host, the HTTP method, the geographic origin, and the result of a CAPTCHA challenge. For the description of every field, refer to botManagerMetrics.
Rank the classifications by volume
Ordering by the aggregate instead of by the timestamp turns the same dataset into a ranking, so you read which combinations account for the most traffic. Two changes to the query above produce it:
- Set
orderByto[sum_DESC], so the largest groups come first. - Drop
tsfromgroupBy, so each combination collapses into one object across the whole range.
The result groups the period by classification, category, and action:
The objects at the top of the response are the largest groups, which is where a change of threshold or of action moves the most traffic. For more information on reading these counts back into a configuration, refer to Monitor and calibrate Bot Manager.