# GraphQL API limits

The [GraphQL API](/en/documentation/devtools/graphql/) applies fixed bounds to every query: the rows it returns, the fields it selects, and how far back raw data goes. The length of the time range also sets the time interval of each row an aggregated query returns.

---

## Query bounds

A query past a row or field bound returns HTTP `400`, with the message in the `detail` key of a JSON body, not in a GraphQL `errors` array. Raw data older than the retention period returns no error:

| Scope                                             | Limit            | Past the limit                                                                                                                                           |
| ------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rows per query, set by `limit`                    | 0 to 10,000 rows | `400` with `The value for the query limit is invalid (must be between 0 to 10000 rows).`                                                                 |
| Selected fields, datasets of the metrics endpoint | 37 fields        | `400` with `You have exceeded the limit amount allowed for selected fields (37 fields).`                                                                 |
| Selected fields, `workloadEvents`                 | 36 fields        | At 37 fields, `400` with `The query has reached a system limit. Please adjust your query and try again.` At 38 or more, `400` with the 37-field message. |
| Raw data on the events endpoint                   | About 7 days     | The query returns `200` with the records inside the retention period and none older.                                                                     |

Without `limit`, a query returns 10 rows. The `offset` argument, `0` by default, sets how many rows the API skips before it returns them. The output field of an aggregate function, such as `sum`, does not count toward the 37 fields: a `workloadMetrics` query that selects `ts`, 36 other fields, and `sum` succeeds.

On `workloadEvents`, the 37th field returns the system-limit message whatever the field and the time range. For example, a `workloadEvents` query that selects 37 fields fails, and the same query at 36 fields succeeds.

This query asks for 10,001 rows:

```graphql
query {
  workloadMetrics(limit: 10001, filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} }, aggregate: { sum: requests }, groupBy: [ts]) {
    ts
    sum
  }
}
```

The API refuses it with `400` and this body:

```json
{
  "detail": "The value for the query limit is invalid (must be between 0 to 10000 rows)."
}
```

Every message the API returns, with its cause, is on [Error responses](/en/documentation/devtools/graphql/error-responses/).

---

## Time interval of aggregated rows

An aggregated query on the metrics endpoint returns rows grouped into time intervals. The adaptive resolver sets the interval from the length of the time range, so a longer range returns fewer, wider rows:

| Time range length  | Interval of each row |
| ------------------ | -------------------- |
| Up to about 2 days | 1 minute             |
| From 60 hours      | 1 hour               |
| From about 60 days | 1 day                |

For example, a range of 48 hours or less returns one row per minute, such as `13:34:00`, and a range of 59 days returns one row per hour. The switch to a wider interval returns no error.

This query sums the requests of a 61-day range per interval, latest first:

```graphql
query {
  workloadMetrics(limit: 3, filter: { tsRange: {begin: "2026-08-03T14:00:00", end: "2026-10-03T14:00:00"} }, aggregate: { sum: requests }, groupBy: [ts], orderBy: [ts_DESC]) {
    ts
    sum
  }
}
```

The response holds one row per day:

```json
{
  "data": {
    "workloadMetrics": [
      {
        "ts": "2026-10-03T00:00:00Z",
        "sum": 7
      },
      {
        "ts": "2026-10-02T00:00:00Z",
        "sum": 766
      },
      {
        "ts": "2026-10-01T00:00:00Z",
        "sum": 1761
      }
    ]
  }
}
```

For the query shape, refer to [Queries](/en/documentation/devtools/graphql/queries/#aggregated-data).

---

## Related resources

- [Error responses](/en/documentation/devtools/graphql/error-responses.md): The status codes and messages a refused query returns, and what causes each one.
- [Datasets and query arguments](/en/documentation/devtools/graphql/features.md): The datasets of each endpoint and the filter, sort, and pagination arguments a query accepts.
- [Queries](/en/documentation/devtools/graphql/queries.md): The shape of a raw, aggregated, financial, and usage query, with a response for each.
- [Glossary](/en/documentation/devtools/graphql/glossary.md): The terms the GraphQL API pages use, such as adaptive resolver and raw data.