# Limites da GraphQL API

A [GraphQL API](/pt-br/documentacao/devtools/graphql/) aplica limites fixos a toda query: as linhas que ela retorna, os campos que ela seleciona e a antiguidade máxima dos dados brutos. A duração da janela de tempo também define o intervalo de tempo de cada linha que uma query agregada retorna.

---

## Limites de query

Uma query que ultrapassa um limite de linhas ou de campos retorna HTTP `400`, com a mensagem na chave `detail` de um corpo JSON, não em um array `errors` da GraphQL. Dados brutos mais antigos que o período de retenção não retornam erro:

| Escopo                                               | Limite            | Após o limite                                                                                                                                               |
| ---------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Linhas por query, definidas por `limit`              | 0 a 10.000 linhas | `400` com `The value for the query limit is invalid (must be between 0 to 10000 rows).`                                                                     |
| Campos selecionados, datasets do endpoint de metrics | 37 campos         | `400` com `You have exceeded the limit amount allowed for selected fields (37 fields).`                                                                     |
| Campos selecionados, `workloadEvents`                | 36 campos         | Com 37 campos, `400` com `The query has reached a system limit. Please adjust your query and try again.` Com 38 ou mais, `400` com a mensagem de 37 campos. |
| Dados brutos no endpoint de events                   | Cerca de 7 dias   | A query retorna `200` com os registros dentro do período de retenção e nenhum mais antigo.                                                                  |

Sem `limit`, uma query retorna 10 linhas. O argumento `offset`, `0` por padrão, define quantas linhas a API pula antes de retorná-las. O campo de saída de uma função de agregação, como `sum`, não conta para os 37 campos: uma query de `workloadMetrics` que seleciona `ts`, outros 36 campos e `sum` é bem-sucedida.

Em `workloadEvents`, o 37º campo retorna a mensagem de limite do sistema, quaisquer que sejam o campo e a janela de tempo. Por exemplo, uma query de `workloadEvents` que seleciona 37 campos falha, e a mesma query com 36 campos é bem-sucedida.

Esta query pede 10.001 linhas:

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

A API a recusa com `400` e este corpo:

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

Todas as mensagens que a API retorna, com a sua causa, estão em [Respostas de erro](/pt-br/documentacao/devtools/graphql/mensagens-erro/).

---

## Intervalo de tempo das linhas agregadas

Uma query agregada no endpoint de metrics retorna linhas agrupadas em intervalos de tempo. O resolvedor adaptativo define o intervalo a partir da duração da janela de tempo, então uma janela mais longa retorna menos linhas, mais largas:

| Duração da janela de tempo   | Intervalo de cada linha |
| ---------------------------- | ----------------------- |
| Até cerca de 2 dias          | 1 minuto                |
| A partir de 60 horas         | 1 hora                  |
| A partir de cerca de 60 dias | 1 dia                   |

Por exemplo, uma janela de 48 horas ou menos retorna uma linha por minuto, como `13:34:00`, e uma janela de 59 dias retorna uma linha por hora. A troca para um intervalo mais largo não retorna erro.

Esta query soma as requisições de uma janela de 61 dias por intervalo, da mais recente para a mais antiga:

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

A resposta contém uma linha por dia:

```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
      }
    ]
  }
}
```

Para o formato da query, consulte [Queries](/pt-br/documentacao/devtools/graphql/queries/#dados-agregados).

---

## Recursos relacionados

- [Respostas de erro](/pt-br/documentacao/devtools/graphql/mensagens-erro.md): Os códigos de status e as mensagens que uma query recusada retorna, e o que causa cada um.
- [Datasets e argumentos de query](/pt-br/documentacao/devtools/graphql/recursos.md): Os datasets de cada endpoint e os argumentos de filtro, ordenação e paginação que uma query aceita.
- [Queries](/pt-br/documentacao/devtools/graphql/queries.md): O formato de uma query de dados brutos, agregados, financeiros e de uso, com uma resposta para cada um.
- [Glossário](/pt-br/documentacao/devtools/graphql/glossario.md): Os termos que as páginas da GraphQL API usam, como resolvedor adaptativo e dados brutos.