> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultando métricas

Leia dados de métrica com a [API pública (V2)](/api/v2/overview). Busque uma
timeseries para gráficos, uma lista agregada para tabelas ou descubra quais métricas
e tags um site possui. Todos os endpoints autenticam com seu token pessoal de API e
têm escopo de um único `site_id`.

## Consultar uma timeseries

Este endpoint retorna uma ou mais séries de pontos de dados ao longo de um intervalo de tempo. Use-o
para desenhar gráficos.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/metrics/timeseries
  ```
</CodeGroup>

### Corpo da requisição

| Campo        | Tipo                  | Obrigatório | Descrição                                                                  |
| ------------ | --------------------- | ----------- | -------------------------------------------------------------------------- |
| `site_id`    | string                | Sim         | Site a ser consultado.                                                     |
| `from`       | string (ISO 8601)     | Sim         | Início do intervalo de tempo (inclusivo).                                  |
| `to`         | string (ISO 8601)     | Sim         | Fim do intervalo de tempo (inclusivo).                                     |
| `select`     | TimeseriesSelector\[] | Sim         | Quais métricas, campos e tags buscar.                                      |
| `resolution` | Resolution            | Não         | Intervalo entre pontos de dados. Escolhido automaticamente quando omitido. |
| `limit`      | number                | Não         | Número máximo de séries a retornar.                                        |

Cada entrada de `select` recebe um `name` de métrica, um objeto `tags` para filtrar (os valores
podem usar `*` como wildcard), um `field` (veja [fields](#fields)), uma `aggregation`
opcional (veja [aggregations](#aggregations)) e `draw_null_as_zero` (quando `true`, pontos ausentes são preenchidos com `0`).

<CodeGroup>
  ```json body.json theme={null}
  {
    "site_id": "YOUR-SITE-ID",
    "from": "2026-06-22T00:00:00Z",
    "to": "2026-06-22T01:00:00Z",
    "resolution": "MINUTELY",
    "select": [
      {
        "name": "transaction_duration",
        "tags": { "namespace": "web" },
        "field": "mean",
        "aggregation": "avg",
        "draw_null_as_zero": false
      }
    ],
    "limit": null
  }
  ```
</CodeGroup>

### Resposta

Retorna um `Timeseries` com a `resolution`, `from`, `to` consultados e um array
`series`. Cada série tem um `id`, o `name` da métrica, suas `tags`, o
`field` que ela representa, `min` e `max` no intervalo e um array `data` de
pontos. Cada ponto tem um `timestamp` e um `value` numérico.

## Consultar uma lista

Este endpoint retorna valores de métrica agregados agrupados em linhas. Use-o para construir
tabelas.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/metrics/list
  ```
</CodeGroup>

### Corpo da requisição

| Campo        | Tipo              | Obrigatório | Descrição                                 |
| ------------ | ----------------- | ----------- | ----------------------------------------- |
| `site_id`    | string            | Sim         | Site a ser consultado.                    |
| `from`       | string (ISO 8601) | Sim         | Início do intervalo de tempo (inclusivo). |
| `to`         | string (ISO 8601) | Sim         | Fim do intervalo de tempo (inclusivo).    |
| `select`     | ListSelector\[]   | Sim         | Quais métricas, campos e tags buscar.     |
| `group_by`   | GroupBy\[]        | Sim         | Como agrupar as linhas.                   |
| `resolution` | Resolution        | Não         | Intervalo usado para agregação.           |
| `limit`      | number            | Não         | Número máximo de linhas a retornar.       |

Um `ListSelector` é como um seletor de timeseries, com um `id` extra que nomeia o
valor do seletor no objeto `data` de cada linha. As entradas de `group_by` são `Name` (agrupa
por nome da métrica) ou `Tag` (agrupa pelo valor de uma tag).

<CodeGroup>
  ```json body.json theme={null}
  {
    "site_id": "YOUR-SITE-ID",
    "from": "2026-06-22T00:00:00Z",
    "to": "2026-06-22T01:00:00Z",
    "resolution": "HOURLY",
    "select": [
      {
        "id": "mean",
        "name": "transaction_duration",
        "tags": { "namespace": "*" },
        "field": "mean",
        "aggregation": "avg"
      }
    ],
    "group_by": ["Name"],
    "limit": 50
  }
  ```
</CodeGroup>

### Resposta

Retorna uma `List` com a `resolution`, `from`, `to` consultados e um array `rows`.
Cada linha tem um `id`, um objeto `group` com os valores de tag que a definem e um
objeto `data` com valores agregados indexados pelo `id` do seletor (por exemplo,
`{ "mean": 42.5 }`).

## Listar nomes de métrica

Retorna todos os nomes de métrica disponíveis para um site.

<CodeGroup>
  ```shell Endpoint theme={null}
  GET /api/v2/metrics/names/{site_id}
  ```
</CodeGroup>

Retorna um array de strings.

## Obter o tipo e as tags de uma métrica

Retorna o tipo de uma métrica e as combinações de tags com que ela pode ser consultada.

<CodeGroup>
  ```shell Endpoint theme={null}
  GET /api/v2/metrics/type_and_tags/{site_id}/{metric_name}
  ```
</CodeGroup>

Retorna um `metric_type` (`gauge`, `counter` ou `measurement`) e
`available_tags`, um array em que cada entrada é uma combinação válida de chaves de tag.

## Referência

### Fields

O `field` seleciona qual medição obter de uma métrica:

| Valor          | Descrição                                                                                                      |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `gauge`        | O valor da métrica em um único instante, como uso atual de CPU ou memória.                                     |
| `counter`      | De métricas `counter`, o valor cumulativo, que só aumenta com o tempo, como o número de requisições atendidas. |
| `mean`         | A média dos valores registrados no bucket de tempo, como tempo médio de resposta.                              |
| `count`        | De métricas `measurement`, quantos valores foram registrados durante o bucket de tempo.                        |
| `min`          | O menor valor registrado no bucket de tempo.                                                                   |
| `max`          | O maior valor registrado no bucket de tempo.                                                                   |
| `p_90`, `p_95` | Valores de percentil.                                                                                          |

Para mais referências de tipo, leia a [documentação da API V2 da AppSignal](https://appsignal.com/api/v2/docs).

### Aggregations

A `aggregation` combina vários valores dentro de um bucket de tempo: `sum`, `avg`,
`min`, `max`, `first` ou `last`.

### Resolutions

`resolution` aceita `MINUTELY`, `FIVE_MINUTELY`, `TEN_MINUTELY`,
`FIFTEEN_MINUTELY`, `HOURLY` ou `DAILY`.