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

# Read Metrics

> Returns aggregated message counters for one or several instances

**Auth:** `TokenAccount` or `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotent:** yes

## Description

Returns message counters (total, by type, by status, last 7/30 days, unique contacts, etc.) for an instance **or** a consolidated set of several at once.

## How it works

The `:instance` parameter accepts two formats:

* **A single instance**: `/metrics/sales` returns its metrics
* **Multiple instances**: `/metrics/sales,support,marketing` returns **a single object** with the values **summed** across them

When you pass several, numeric values are summed, timestamps return the smallest/largest (first message / last message), and the `instance` field of the response brings the original list.

## Examples

### One instance

Passing a single name in the path returns the metrics of that instance in isolation, ideal for individual dashboards or for reading statistics of a specific number.

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

### Multiple (consolidated)

Passing several names separated by comma returns **a single object** with numeric values summed across instances. Useful for aggregated views per department or account.

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

## Path parameters

<ParamField path="instance" type="string" required>
  Single name (e.g., `sales`) or comma-separated list (e.g., `sales,support`). Spaces around commas are accepted.
</ParamField>

## Headers

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

## Success response

<Tabs>
  <Tab title="One instance">
    ```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="Multiple (consolidated)">
    ```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>

## Response fields

| Field                                             | What it is                                                                     |
| ------------------------------------------------- | ------------------------------------------------------------------------------ |
| `totalMessages`                                   | Total messages sent + received                                                 |
| `messagesReceived` / `messagesSent`               | Breakdown by direction                                                         |
| `messagesByType`                                  | Count by type (`text`, `image`, `audio`, `video`, `document`, `sticker`, etc.) |
| `groupMessages` / `individualMessages`            | Group vs 1-to-1 breakdown                                                      |
| `messagesWithMedia`                               | How many had attached media                                                    |
| `mediaByType`                                     | Media count by type                                                            |
| `messagesByStatus`                                | Status breakdown (`pending`, `sent`, `delivered`, `read`, `played`, `failed`)  |
| `uniqueChats` / `uniqueGroups` / `uniqueContacts` | Unique counts                                                                  |
| `messagesLast7Days` / `messagesLast30Days`        | Recency                                                                        |
| `firstMessageAt` / `lastMessageAt`                | Edge dates                                                                     |

## Errors

| HTTP | Condition                               |
| :--: | --------------------------------------- |
|  400 | Empty path or only commas               |
|  401 | Token missing or invalid                |
|  404 | Any instance in the list does not exist |
|  429 | More than 100 requests per minute       |

## Notes

<Note>
  If the instance has `ignoreGroupMessages` active, group messages **are not counted**, `groupMessages` may appear as `0`.
</Note>

<Warning>
  For high-frequency dashboards, consider storing the values on your side, each call performs full computations and can take time on instances with high volume.
</Warning>

## Next

<CardGroup cols={2}>
  <Card title="List instances" icon="list" href="/en/api/instance/list">
    Current connection state and integrations summary.
  </Card>

  <Card title="Update settings" icon="sliders" href="/en/api/instance/settings-update">
    Adjust behavior flags such as `ignoreGroupMessages`.
  </Card>
</CardGroup>