# Listar conexões

Fonte: https://apiwpp.com/docs/api/conexoes/listar-conexoes
Seção: Conexões
Atualizado em: 2026-09-28

`GET /connections`

As conexões dos projetos ativos de quem chama, das mais novas para as mais antigas, cada uma com o status atual. As conexões com status `failed` (falha permanente, por exemplo um número banido) ficam de fora, a menos que `includeFailed=true`. Escopo necessário: `connections:read`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |

## Parâmetros de consulta

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `includeFailed` | `boolean` | não | Inclui as conexões com status `failed` (falha permanente). Padrão: `false`. (padrão: false) |

## Exemplo de requisição

### cURL

```bash
curl https://api.apiwpp.com/connections \
  -H "Authorization: Bearer $API_KEY"
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/connections`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->get("https://api.apiwpp.com/connections");
```

### Python

```python
import requests

response = requests.get(
    "https://api.apiwpp.com/connections",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | As conexões (`connections`), das mais novas para as mais antigas, e quantas são (`count`). |
| 400 | `FST_ERR_VALIDATION` | A requisição não segue o schema da operação (por exemplo, um `id` que não é um UUID); `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é `{"error": "Unauthorized"}`. |
| 403 |  | A chave não tem o escopo `connections:read`; a mensagem de erro cita o escopo que falta. |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de `Retry-After`. Cabeçalhos: `Retry-After`. |

### 200 OK

```json
{
  "connections": [
    {
      "id": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
      "tenantName": "acme-crm",
      "externalId": "shop-42",
      "status": "open",
      "phoneNumber": "5511900000001",
      "lastHeartbeat": "2026-09-24T12:00:00.000Z",
      "lastConnectedAt": "2026-09-24T08:00:00.000Z",
      "createdAt": "2026-09-01T12:00:00.000Z"
    }
  ],
  "count": 1
}
```

## Detalhes

`status` é o status ao vivo quando a instância que responde roda a conexão (`connecting`, `open`, `close` ou `passkey_required`); senão, é o último gravado, em minúsculas: `pending`, `connecting`, `open`, `close`, `failed` ou `passkey_required`. Para um número só, `GET /connections/{id}/qr` sempre responde o status ao vivo.

`externalId` é o identificador que você deu à conexão ao criá-la; `lastHeartbeat` é a última vez que o gateway confirmou que o socket responde, e `lastConnectedAt`, a última vez que a conexão abriu.

Guia: [Projetos e conexões](https://apiwpp.com/docs/guias/projetos-e-conexoes).
