> ## 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.

# Leer métricas

> Devuelve contadores agregados de mensajes para una o varias instancias

**Auth:** `TokenAccount` o `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** sí

## Descripción

Devuelve contadores de mensajes (total, por tipo, por status, últimos 7/30 días, contactos únicos, etc.) para una instancia **o** un conjunto consolidado de varias a la vez.

## Cómo funciona

El parámetro `:instance` acepta dos formatos:

* **Una sola instancia**: `/metrics/sales` devuelve sus métricas
* **Múltiples instancias**: `/metrics/sales,support,marketing` devuelve **un único objeto** con los valores **sumados** entre ellas

Cuando pasas varias, los valores numéricos se suman, los timestamps devuelven el menor/mayor (primer mensaje / último mensaje), y el campo `instance` de la respuesta trae la lista original.

## Ejemplos

### Una instancia

Pasando un único nombre en el path devuelve las métricas de esa instancia de forma aislada, ideal para dashboards individuales o para leer estadísticas de un número específico.

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

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

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

  requests.get(
      "https://ryzeapi.cloud/api/instance/metrics/sales",
      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/sales", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Múltiples (consolidado)

Pasando varios nombres separados por coma devuelve **un único objeto** con valores numéricos sumados entre las instancias. Útil para vistas agregadas por departamento o cuenta.

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

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

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

  requests.get(
      "https://ryzeapi.cloud/api/instance/metrics/sales,support,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/sales,support,marketing", nil)
      req.Header.Set("token", os.Getenv("Token_Account"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

## Parámetros de ruta

<ParamField path="instance" type="string" required>
  Un único nombre (p. ej., `sales`) o lista separada por coma (p. ej., `sales,support`). Espacios alrededor de las comas son aceptados.
</ParamField>

## Cabeceras

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

## Respuesta exitosa

<Tabs>
  <Tab title="Una instancia">
    ```json 200 OK theme={null}
    {
      "success": true,
      "message": "Metrics retrieved successfully",
      "metrics": {
        "instance": "sales",
        "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últiples (consolidado)">
    ```json 200 OK theme={null}
    {
      "success": true,
      "message": "Metrics retrieved successfully",
      "metrics": {
        "instance": "sales,support",
        "totalMessages": 3410,
        "messagesReceived": 2105,
        "messagesSent": 1305,
        "messagesByType": {
          "text": 2890,
          "image": 290,
          "audio": 130
        },
        "...": "... other summed fields"
      }
    }
    ```
  </Tab>
</Tabs>

## Campos de respuesta

| Campo                                             | Qué es                                                                           |
| ------------------------------------------------- | -------------------------------------------------------------------------------- |
| `totalMessages`                                   | Total de mensajes enviados + recibidos                                           |
| `messagesReceived` / `messagesSent`               | Desglose por dirección                                                           |
| `messagesByType`                                  | Conteo por tipo (`text`, `image`, `audio`, `video`, `document`, `sticker`, etc.) |
| `groupMessages` / `individualMessages`            | Desglose grupo vs 1-a-1                                                          |
| `messagesWithMedia`                               | Cuántos tenían media adjunta                                                     |
| `mediaByType`                                     | Conteo de media por tipo                                                         |
| `messagesByStatus`                                | Desglose por status (`pending`, `sent`, `delivered`, `read`, `played`, `failed`) |
| `uniqueChats` / `uniqueGroups` / `uniqueContacts` | Conteos únicos                                                                   |
| `messagesLast7Days` / `messagesLast30Days`        | Recencia                                                                         |
| `firstMessageAt` / `lastMessageAt`                | Fechas extremas                                                                  |

## Errores

| HTTP | Condición                                 |
| :--: | ----------------------------------------- |
|  400 | Path vacío o solo comas                   |
|  401 | Token faltante o inválido                 |
|  404 | Cualquier instancia de la lista no existe |
|  429 | Más de 100 solicitudes por minuto         |

## Notas

<Note>
  Si la instancia tiene `ignoreGroupMessages` activo, los mensajes de grupo **no se cuentan**, `groupMessages` puede aparecer como `0`.
</Note>

<Warning>
  Para dashboards de alta frecuencia, considera almacenar los valores de tu lado, cada llamada realiza cómputos completos y puede tardar en instancias de alto volumen.
</Warning>

## Siguiente

<CardGroup cols={2}>
  <Card title="Listar instancias" icon="list" href="/es/api/instance/list">
    Estado actual de conexión y resumen de integraciones.
  </Card>

  <Card title="Actualizar settings" icon="sliders" href="/es/api/instance/settings-update">
    Ajusta flags de comportamiento como `ignoreGroupMessages`.
  </Card>
</CardGroup>