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

# Estatísticas da Instância

> Métricas agregadas de mensagens e conversas sincronizadas da Meta, com séries temporais e breakdown por status.

## Parâmetros

<ParamField path="instanceId" type="string" required>
  ID da instância.
</ParamField>

<ParamField query="from" type="string">
  Data de início (ISO 8601 ou `YYYY-MM-DD`). Padrão: 30 dias atrás.
</ParamField>

<ParamField query="to" type="string">
  Data de fim (ISO 8601 ou `YYYY-MM-DD`). Padrão: hoje.
</ParamField>

<ParamField query="groupBy" type="string" default="day">
  Agrupamento das séries temporais: `day`, `week` ou `month`.
</ParamField>

## Exemplo de Requisição

```bash theme={null}
curl --request GET \
  --url 'https://apis.vectalk.com.br/api/analytics/instances/{instanceId}/stats?from=2026-01-01&to=2026-01-31&groupBy=day' \
  --header 'Authorization: Bearer {seu_token}'
```

## Resposta

```json theme={null}
{
  "summary": {
    "totalSent": 1250,
    "totalReceived": 340,
    "totalDelivered": 1180,
    "totalRead": 950,
    "totalFailed": 15,
    "deliveryRate": 94,
    "readRate": 76,
    "failureRate": 1,
    "source": "meta"
  },
  "byStatus": [
    { "status": "SENT", "count": 1250 },
    { "status": "DELIVERED", "count": 230 },
    { "status": "READ", "count": 950 },
    { "status": "FAILED", "count": 15 }
  ],
  "timeSeries": [
    {
      "period": "2026-01-01",
      "sent": 42,
      "delivered": 40,
      "read": 35
    }
  ],
  "conversations": {
    "total": 200,
    "totalCost": 50.5,
    "byCategory": [
      { "label": "MARKETING", "conversation": 80, "cost": 20.0 },
      { "label": "UTILITY", "conversation": 120, "cost": 30.5 }
    ],
    "byType": [
      { "label": "REGULAR", "conversation": 200, "cost": 50.5 }
    ]
  },
  "channel": {
    "qualityRating": "GREEN",
    "verifiedName": "Minha Empresa",
    "displayPhoneNumber": "+55 11 99999-9999",
    "status": "ACTIVE"
  }
}
```

### Campos da Resposta

| Campo                  | Descrição                                                             |
| ---------------------- | --------------------------------------------------------------------- |
| `summary.source`       | `meta` se dados vêm da Meta, `local` se vêm do banco local (fallback) |
| `summary.deliveryRate` | Porcentagem de entrega (delivered + read / sent)                      |
| `summary.readRate`     | Porcentagem de leitura (read / sent)                                  |
| `timeSeries`           | Série temporal agrupada por `groupBy`                                 |
| `conversations`        | Dados de conversas sincronizados da Meta (últimos 90 dias)            |
| `channel`              | Metadados do número (quality rating, nome verificado)                 |

<Note>
  Os dados são sincronizados da Meta diariamente. Use `POST /analytics/instances/{instanceId}/sync` para forçar sincronização.
</Note>