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

# instance

> Listagem e inspeção de instâncias WhatsApp.

## `zapsterapi instance list`

Lista as instâncias WhatsApp disponíveis para o perfil ativo.

```bash theme={null}
zapsterapi instance list \
  [--status <connected|offline|disconnected>] \
  [--lookup-key <chave>] \
  [--page <n>] \
  [--per-page <n>] \
  [-q, --query <texto>] \
  [--profile <nome>] \
  [--json]
```

| Flag                   | Obrigatório | Descrição                                                              |
| ---------------------- | ----------- | ---------------------------------------------------------------------- |
| `--status <status>`    | Não         | Filtra por status: `connected`, `offline` ou `disconnected`.           |
| `--lookup-key <chave>` | Não         | Filtra por `lookup_key` (chave externa que você associou à instância). |
| `--page <n>`           | Não         | Página (default: 1).                                                   |
| `--per-page <n>`       | Não         | Itens por página (default: 15, máx: 100).                              |
| `-q, --query <texto>`  | Não         | Busca textual no nome da instância.                                    |

Saída texto (default):

```
ID                    NAME            STATUS     CONNECTION
i_01HABC...           Atendimento     connected  unofficial
i_01HXYZ...           Marketing       offline    unofficial
```

Saída JSON:

```json theme={null}
{
  "ok": true,
  "data": {
    "instances": [
      {
        "id": "i_01HABC...",
        "name": "Atendimento",
        "status": "connected",
        "connection_type": "unofficial"
      }
    ],
    "total": 1
  }
}
```

### Exemplos

```bash theme={null}
# Apenas instâncias conectadas
zapsterapi instance list --status connected

# Procurar por nome
zapsterapi instance list -q "atendimento"

# Paginação
zapsterapi instance list --page 2 --per-page 50
```

A v1 da CLI cobre apenas a listagem. Para criar, atualizar ou desligar instâncias, use a [REST API](/pt-BR/v1/api-reference/instance/list-instances).