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

# Verificar Métricas

> Retorna contadores agregados de mensagens de uma ou várias instâncias

**Auth:** `TokenAccount` ou `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** sim

## Descrição

Retorna contadores de mensagens (total, por tipo, por status, últimos 7/30 dias, contatos únicos, etc.) para uma instância **ou** um conjunto consolidado de várias ao mesmo tempo.

## Como funciona

O parâmetro `:instance` aceita dois formatos:

* **Uma instância única**: `/metrics/vendas` retorna as métricas dela
* **Múltiplas instâncias**: `/metrics/vendas,suporte,marketing` retorna **um único objeto** com os valores **somados** entre elas

Quando você passa várias, os valores numéricos são somados, os timestamps retornam o menor/maior (primeira mensagem / última mensagem), e o campo `instance` da resposta traz a lista original.

## Exemplos

### Uma instância

Passando um único nome no path, retorna as métricas daquela instância isoladamente, ideal para dashboards individuais ou para ler estatísticas de um número específico.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/metrics/vendas" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/metrics/vendas", {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/instance/metrics/vendas",
      headers={
          "token": os.environ["Token_Instance"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/metrics/vendas", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Múltiplas (consolidado)

Passando vários nomes separados por vírgula, retorna **um único objeto** com os valores numéricos somados entre as instâncias. Útil para visões agregadas de departamento ou conta.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/metrics/vendas,suporte,marketing" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/metrics/vendas,suporte,marketing", {
    method: "GET",
    headers: {
      "token": process.env.Token_Account
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/instance/metrics/vendas,suporte,marketing",
      headers={
          "token": os.environ["Token_Account"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/metrics/vendas,suporte,marketing", nil)
      req.Header.Set("token", os.Getenv("Token_Account"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

## Path parameters

<ParamField path="instance" type="string" required>
  Nome único (ex.: `vendas`) ou lista separada por vírgula (ex.: `vendas,suporte`). Espaços ao redor das vírgulas são aceitos.
</ParamField>

## Headers

<ParamField header="token" type="string" required>
  TokenAccount ou TokenInstance.
</ParamField>

## Resposta de sucesso

<Tabs>
  <Tab title="Uma instância">
    ```json 200 OK theme={null}
    {
      "success": true,
      "message": "Metrics retrieved successfully",
      "metrics": {
        "instance": "vendas",
        "totalMessages": 1523,
        "messagesReceived": 981,
        "messagesSent": 542,
        "messagesByType": {
          "text": 1205,
          "image": 187,
          "audio": 72,
          "video": 34,
          "document": 15,
          "sticker": 10
        },
        "groupMessages": 384,
        "individualMessages": 1139,
        "messagesWithMedia": 318,
        "mediaByType": {
          "image": 187,
          "audio": 72,
          "video": 34,
          "document": 15,
          "sticker": 10
        },
        "messagesByStatus": {
          "sent": 542,
          "received": 981,
          "delivered": 320,
          "read": 210,
          "pending": 12
        },
        "uniqueChats": 97,
        "uniqueGroups": 14,
        "uniqueContacts": 83,
        "messagesLast7Days": 412,
        "messagesLast30Days": 1287,
        "firstMessageAt": "2026-02-01T15:32:10Z",
        "lastMessageAt": "2026-04-18T23:14:55Z"
      }
    }
    ```
  </Tab>

  <Tab title="Múltiplas (consolidado)">
    ```json 200 OK theme={null}
    {
      "success": true,
      "message": "Metrics retrieved successfully",
      "metrics": {
        "instance": "vendas,suporte",
        "totalMessages": 3410,
        "messagesReceived": 2105,
        "messagesSent": 1305,
        "messagesByType": {
          "text": 2890,
          "image": 290,
          "audio": 130
        },
        "...": "... demais campos somados"
      }
    }
    ```
  </Tab>
</Tabs>

## Campos da resposta

| Campo                                             | O que é                                                                            |
| ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `totalMessages`                                   | Total de mensagens enviadas + recebidas                                            |
| `messagesReceived` / `messagesSent`               | Quebra por direção                                                                 |
| `messagesByType`                                  | Contagem por tipo (`text`, `image`, `audio`, `video`, `document`, `sticker`, etc.) |
| `groupMessages` / `individualMessages`            | Quebra entre grupo e 1-a-1                                                         |
| `messagesWithMedia`                               | Quantas tinham mídia anexada                                                       |
| `mediaByType`                                     | Contagem de mídias por tipo                                                        |
| `messagesByStatus`                                | Quebra por status (`pending`, `sent`, `delivered`, `read`, `played`, `failed`)     |
| `uniqueChats` / `uniqueGroups` / `uniqueContacts` | Contagens únicas                                                                   |
| `messagesLast7Days` / `messagesLast30Days`        | Recência                                                                           |
| `firstMessageAt` / `lastMessageAt`                | Datas extremas                                                                     |

## Erros

| HTTP | Condição                               |
| :--: | -------------------------------------- |
|  400 | Path vazio ou só com vírgulas          |
|  401 | Token ausente ou inválido              |
|  404 | Qualquer instância da lista não existe |
|  429 | Mais de 100 requisições por minuto     |

## Notas

<Note>
  Se a instância tiver `ignoreGroupMessages` ativo, mensagens de grupo **não são contadas**, `groupMessages` pode aparecer como `0`.
</Note>

<Warning>
  Para dashboards de alta frequência, considere armazenar os valores no seu lado, cada chamada executa cálculos completos e pode demorar em instâncias com muito volume.
</Warning>

## Próximo

<CardGroup cols={2}>
  <Card title="Listar instâncias" icon="list" href="/pt/api/instance/list">
    Estado atual de conexão e resumo das integrações.
  </Card>

  <Card title="Atualizar settings" icon="sliders" href="/pt/api/instance/settings-update">
    Ajuste flags de comportamento como `ignoreGroupMessages`.
  </Card>
</CardGroup>