---
name: azion-query-the-httpbreakdownmetrics-dataset
description: >-
  List the client IP addresses with the most blocked requests from the httpBreakdownMetrics dataset, with curl or the GraphiQL playground.
---

# Query the httpBreakdownMetrics dataset

You can list the client IP addresses with the most blocked requests with the GraphQL API, from `curl` or the GraphiQL playground.

The `httpBreakdownMetrics` dataset of [Real-Time Metrics](/en/documentation/platform/real-time-metrics/) splits the requests to your applications by values such as `remoteAddress`, the IP address of the client, `geolocCountryName`, and `requestPath`. For each combination of values, it counts `requests`, `blockedRequests`, and `wafThreatRequests`. For every field and filter of the dataset, refer to [Real-Time Metrics GraphQL fields](/en/documentation/devtools/graphql/gql-real-time-metrics-fields/#workloadbreakdownmetrics).

The dataset returns hour buckets, even for a range of one hour. For how the range sets the bucket size, refer to [How Real-Time Metrics works](/en/documentation/platform/real-time-metrics/how-it-works/#resolution). Real-Time Metrics keeps the data of `httpBreakdownMetrics` for 90 days. For the retention of every dataset, refer to [Real-Time Metrics limits](/en/documentation/platform/real-time-metrics/limits/#data-retention).

---

## Prerequisites

- A personal token, for `curl`. To create one, refer to [How to manage a personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/).
- `curl`, or the GraphiQL playground. The playground needs a browser session signed in to your Azion account, or it returns an error. To open it, refer to [GraphiQL Playground](/en/documentation/devtools/graphql/graphql-playground/).

---

## List the addresses with the most blocked requests

This query adds up `blockedRequests` for each `remoteAddress` over one hour, and returns the 20 addresses with the highest totals:

```graphql
query TopBlockedAddresses {
  httpBreakdownMetrics(
    aggregate: { sum: blockedRequests }
    groupBy: [remoteAddress]
    orderBy: [sum_DESC]
    limit: 20
    filter: {
      tsGte: "2026-10-02T13:00:00"
      tsLt: "2026-10-02T14:00:00"
    }
  ) {
    remoteAddress
    totalBlocked: sum
  }
}
```

Each argument shapes the result:

- `aggregate: { sum: blockedRequests }` totals the blocked requests that pass the filter. The alias `totalBlocked: sum` renames that total in the response.
- `groupBy: [remoteAddress]` returns one total per client IP address.
- `orderBy: [sum_DESC]` lists the highest total first. `[sum_ASC]` lists the lowest first.
- `limit: 20` caps the response at 20 rows. For the maximum, refer to [Real-Time Metrics limits](/en/documentation/platform/real-time-metrics/limits/#graphql-api).
- `filter` keeps only the data that matches its conditions. Here, the conditions set the time range.
- `tsGte` sets the start of the range, which the result includes. `tsLt` sets the end, which the result excludes.

Both dates take the `YYYY-MM-DDTHH:mm:ss` format. Replace the dates in the example with the hour you want to read. `tsGte` and `tsLt` are an alternative to `tsRange`, the range filter of the [Real-Time Metrics quickstart](/en/documentation/platform/real-time-metrics/quickstart/).

To run the query with `curl`, send a `POST` request to `https://api.azion.com/v4/metrics/graphql`. Replace `[TOKEN VALUE]` with your personal token:

```bash
curl -X POST 'https://api.azion.com/v4/metrics/graphql' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token [TOKEN VALUE]' \
  -d '{"query":"query TopBlockedAddresses { httpBreakdownMetrics(aggregate: { sum: blockedRequests }, groupBy: [remoteAddress], orderBy: [sum_DESC], limit: 20, filter: { tsGte: \"2026-10-02T13:00:00\", tsLt: \"2026-10-02T14:00:00\" }) { remoteAddress totalBlocked: sum } }"}'
```

The API answers `200` with one row per address:

```json
{
  "data": {
    "httpBreakdownMetrics": [
      {
        "remoteAddress": "192.0.2.1",
        "totalBlocked": 0
      }
    ]
  }
}
```

Each row pairs an address with its total of blocked requests, highest first, up to 20 rows. An address with no blocked request reads `0` in `totalBlocked`.

An empty `httpBreakdownMetrics` array means no request matched: check that the range falls inside the 90 days of retention. A request without the `Authorization` header returns `401`.

To run the query in the GraphiQL playground instead, paste the query from the first block.

---

## Next steps

- [Find the top sources of WAF threats](/en/documentation/guides/platform/observability/find-top-waf-threat-sources.md): Rank the client IP addresses by the threats WAF finds in their requests.
- [Secure dashboards](/en/documentation/platform/real-time-metrics/secure-dashboards.md#threats-breakdown): See the same dataset as a chart in the Threats Breakdown dashboard of Azion Console.
- [Real-Time Metrics fields](/en/documentation/devtools/graphql/gql-real-time-metrics-fields.md#workloadbreakdownmetrics): Every field, filter, and grouping that httpBreakdownMetrics accepts.
- [Real-Time Metrics limits](/en/documentation/platform/real-time-metrics/limits.md): Retention per dataset, the row cap, and the other bounds of a query.