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

# Histórico de conexões

> A linha do tempo de quando cada número foi vinculado e desvinculado de uma instância

Esta página documenta o **histórico de conexões**, uma linha do tempo auditável de quando cada número de WhatsApp foi vinculado (conectado) e desvinculado (desconectado) de uma instância. Serve para você acompanhar e comprovar qual número esteve conectado em cada momento, útil ao conferir um período faturado com transparência, com o registro na mão.

## Consultar o histórico

**`GET /api/account/connections?number=<jid>&instance=<id>&from=<rfc3339>&to=<rfc3339>&limit=<n>`**

Devolve os eventos de vínculo e desvínculo da conta, mais recentes primeiro. Autentique com o **TokenAccount** da conta, ou com o token global passando `?account=<nome-da-conta>`. Todos os filtros são opcionais: sem nenhum, você recebe os eventos mais recentes da conta.

<ParamField query="number" type="string">
  Filtra por um número específico. Use o JID exato, ex. `5511999998888@s.whatsapp.net`.
</ParamField>

<ParamField query="instance" type="string">
  Filtra por uma instância específica. Use o `instanceId` que aparece nos próprios eventos.
</ParamField>

<ParamField query="from" type="string">
  Início da janela, em RFC3339. Sem ele, não há limite inferior.
</ParamField>

<ParamField query="to" type="string">
  Fim da janela, em RFC3339. Sem ele, não há limite superior.
</ParamField>

<ParamField query="limit" type="integer">
  Máximo de eventos a retornar. Padrão `200`. Valores fora da faixa de `1` a `1000` também usam `200`.
</ParamField>

<ParamField query="account" type="string">
  Nome da conta. Obrigatório apenas quando você usa o token global.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://ryzeapi.cloud/api/account/connections?number=5511999998888@s.whatsapp.net&limit=50" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    number: "5511999998888@s.whatsapp.net",
    limit: "50"
  });

  await fetch(`https://ryzeapi.cloud/api/account/connections?${params}`, {
    headers: { "token": process.env.Token_Account }
  });
  ```

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

  requests.get(
      "https://ryzeapi.cloud/api/account/connections",
      headers={"token": os.environ["Token_Account"]},
      params={"number": "5511999998888@s.whatsapp.net", "limit": 50}
  )
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "events": [
    {
      "instanceId": "9f1c2b3a-7d4e-4a1b-9c2d-3e4f5a6b7c8d",
      "instanceName": "cliente-acme",
      "numberJid": "5511999998888@s.whatsapp.net",
      "event": "unlinked",
      "at": "2026-08-20T09:05:00Z"
    },
    {
      "instanceId": "9f1c2b3a-7d4e-4a1b-9c2d-3e4f5a6b7c8d",
      "instanceName": "cliente-acme",
      "numberJid": "5511999998888@s.whatsapp.net",
      "event": "linked",
      "at": "2026-08-01T12:30:00Z"
    }
  ]
}
```

## Campos da resposta

<ResponseField name="events" type="array">
  Os eventos de conexão, mais recentes primeiro. Uma instância deletada continua com seus eventos, com o nome e o número que ela tinha, pois o registro sobrevive à deleção.

  <Expandable title="campos de cada evento">
    <ResponseField name="instanceId" type="string">
      Identificador da instância. Use este valor no filtro `instance`.
    </ResponseField>

    <ResponseField name="instanceName" type="string">
      Nome da instância no momento do evento.
    </ResponseField>

    <ResponseField name="numberJid" type="string">
      O número de WhatsApp (JID) envolvido no evento.
    </ResponseField>

    <ResponseField name="event" type="string">
      `linked` quando o número foi vinculado (conexão) ou `unlinked` quando foi desvinculado (desconexão).
    </ResponseField>

    <ResponseField name="at" type="string">
      Quando o evento aconteceu, em RFC3339 (UTC).
    </ResponseField>
  </Expandable>
</ResponseField>

## Próximo

<CardGroup cols={2}>
  <Card title="Extrato de uso" icon="receipt" href="/pt/enterprise/statement">
    A fatura com descritivos do período, instância a instância.
  </Card>

  <Card title="Webhooks Enterprise" icon="webhook" href="/pt/enterprise/webhooks">
    Reaja a cada virada de estado por evento.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.