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

# Listar Instâncias

> Retorna as instâncias visíveis para o token, incluindo status, perfil e resumo de cada integração

**Auth:** `TokenAccount` ou `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** sim

## Descrição

Cada item retornado inclui o **status atual**, o estado da conexão, dados de perfil e o resumo das integrações (webhook, websocket, chatwoot, proxy, settings, s3). Esta é a forma recomendada para inspecionar o estado de uma instância.

O resultado depende do tipo de token:

* **TokenAccount**, retorna **todas as instâncias da sua conta**. Aceita filtro `?instanceName=`.
* **TokenInstance**, retorna **apenas a própria instância** do token (filtro é ignorado).

## Exemplos

### Listar todas as instancias da conta

Sem filtro e usando o `TokenAccount`, devolve todas as instâncias visíveis para a conta com status, perfil e resumo das integrações de cada uma.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/list" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/list", {
    method: "GET",
    headers: {
      "token": process.env.Token_Account
    }
  });
  ```

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

  requests.get(
      "https://ryzeapi.cloud/api/instance/list",
      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/list", nil)
      req.Header.Set("token", os.Getenv("Token_Account"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Filtrar por nome único (recomendado para checar status)

Passando `?instanceName=minha-instancia`, retorna apenas aquela instância, ou **404** se não existir. Forma mais barata para fazer poll do estado de conexão após chamar `/connect`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=minha-instancia" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/list?instanceName=minha-instancia", {
    method: "GET",
    headers: {
      "token": process.env.Token_Account
    }
  });
  ```

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

  requests.get(
      "https://ryzeapi.cloud/api/instance/list?instanceName=minha-instancia",
      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/list?instanceName=minha-instancia", nil)
      req.Header.Set("token", os.Getenv("Token_Account"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Filtrar várias

Aceita múltiplos nomes separados por vírgula em `?instanceName=vendas,suporte`. Nomes inexistentes são ignorados silenciosamente, só dá 404 quando o filtro tem um único nome e ele não existe.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=vendas,suporte" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/list?instanceName=vendas,suporte", {
    method: "GET",
    headers: {
      "token": process.env.Token_Account
    }
  });
  ```

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

  requests.get(
      "https://ryzeapi.cloud/api/instance/list?instanceName=vendas,suporte",
      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/list?instanceName=vendas,suporte", nil)
      req.Header.Set("token", os.Getenv("Token_Account"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Ver dados da própria instância

Usando o `TokenInstance`, qualquer filtro é ignorado e a resposta traz somente a instância dona do token. Cenário típico para clientes que só conhecem o token instance e querem inspecionar o próprio estado.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/list" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/list", {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

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

  requests.get(
      "https://ryzeapi.cloud/api/instance/list",
      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/list", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

## Resposta de sucesso

```json 200 OK theme={null}
{
  "success": true,
  "message": "1 Instance found",
  "instances": [
    {
      "id": "5e1d...",
      "name": "minha-instancia",
      "token": "a1b2c3d4-...",
      "status": "connected",
      "connection": {
        "state": "connected",
        "numberJid": "5511999999999@s.whatsapp.net",
        "presenceStatus": "available",
        "displayStatus": "Active"
      },
      "profile": {
        "name": "Orion",
        "pictureUrl": "https://pps.whatsapp.net/...",
        "isBusiness": false,
        "businessName": ""
      },
      "proxy": {
        "enabled": false,
        "host": null,
        "port": null,
        "protocol": null,
        "username": null,
        "password": null
      },
      "webhook": {
        "enabled": true,
        "url": "https://meuapp.com/webhook",
        "events": ["message.exchange"]
      },
      "websocket": {
        "enabled": true,
        "events": ["message.exchange"],
        "mediaBase64": false
      },
      "chatwoot": {
        "enabled": true,
        "status": "active",
        "bridgeIntegrationId": "int_xyz789abc",
        "baseUrl": "https://chatwoot.example.com",
        "accountId": 5,
        "inboxName": "WhatsApp - Orion",
        "apiToken": "sk_live_abc123...",
        "signMessages": true,
        "ignoreGroups": false,
        "startAsPending": false,
        "reopenResolved": true
      },
      "settings": {
        "autoRejectCalls": false,
        "callRejectMessage": "",
        "ignoreGroupMessages": false,
        "keepOnlineStatus": false,
        "autoReadMessages": false,
        "disableHistorySync": true,
        "ignoreStatus": false
      },
      "s3": {
        "enabled": false,
        "region": null,
        "bucket": null,
        "accessKey": null,
        "secretKey": null,
        "endpoint": null,
        "pathPrefix": null
      },
      "createdAt": "2026-04-28T10:30:00Z",
      "updatedAt": "2026-04-28T10:35:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}
```

<Info>
  O campo `message` varia: `"1 Instance found"` quando o total é 1, e `"<N> Instances found"` para outros valores.
</Info>

## Headers

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

## Query parameters

<ParamField query="instanceName" type="string">
  Filtra por nome. Aceita um ou mais nomes separados por vírgula (ex.: `?instanceName=vendas,suporte`). Funciona apenas com TokenAccount.
</ParamField>

## Campos da resposta

### `connection`

| Campo            | Tipo           | Descrição                                                                                 |
| ---------------- | -------------- | ----------------------------------------------------------------------------------------- |
| `state`          | string         | Estado real da conexão whatsmeow (`connected`, `connecting`, `disconnected`, `loggedout`) |
| `numberJid`      | string \| null | JID do número (`5511999999999@s.whatsapp.net`) ou `null` se nunca conectou                |
| `presenceStatus` | string         | `available`, `unavailable`, `composing`...                                                |
| `displayStatus`  | string         | Status amigável para UI                                                                   |

### `profile`

| Campo          | Tipo    | Descrição                                  |
| -------------- | ------- | ------------------------------------------ |
| `name`         | string  | Nome de exibição do WhatsApp               |
| `pictureUrl`   | string  | URL da foto de perfil (cache do whatsmeow) |
| `isBusiness`   | boolean | `true` se é WhatsApp Business              |
| `businessName` | string  | Nome comercial (vazio se não for Business) |

### Integrações

* `webhook`, webhook default (label `default`). `enabled: false` significa sem webhook.
* `websocket`, `{ enabled, events, mediaBase64 }`. `enabled: false` significa que o WebSocket está desligado para a instância.
* `chatwoot`, `{ enabled, status, bridgeIntegrationId, baseUrl, accountId, inboxName, apiToken, signMessages, ignoreGroups, startAsPending, reopenResolved }`. `enabled: false` significa sem integração Chatwoot ligada (ou módulo Chatwoot não habilitado no servidor). O `apiToken` vem em **plaintext** (mesma exposição intencional do [`GET /api/chatwoot/list/:instance`](/pt/api/chatwoot/info)), trate como sensível e só aparece quando há integração. Os quatro flags são **sempre** retornados como `true`/`false` (instâncias sem Chatwoot reportam todos `false` junto de `enabled: false`).
* `proxy`, proxy individual (não inclui o global do deploy).
* `settings`, flags de comportamento (ver [Atualizar settings](/pt/api/instance/settings-update)).
* `s3`, config de storage S3 individual.

## Regras do filtro

| Situação                                       | Comportamento                                              |
| ---------------------------------------------- | ---------------------------------------------------------- |
| TokenAccount sem filtro                        | Retorna todas da conta                                     |
| TokenAccount com 1 nome                        | Retorna aquela específica, ou **404** se não existir       |
| TokenAccount com vários nomes                  | Retorna as que existirem, nomes inexistentes são ignorados |
| TokenAccount com filtro só de vírgulas/espaços | Retorna lista vazia sem erro                               |
| TokenInstance                                  | Ignora filtro; retorna apenas a própria instância          |

## Erros

| HTTP | `error.message`                         | Quando                             |
| :--: | --------------------------------------- | ---------------------------------- |
|  401 | `Invalid token`                         | Token ausente ou inválido          |
|  404 | `Instance not found`                    | Nome único solicitado não existe   |
|  429 | `Rate limit exceeded. Try again later.` | Mais de 100 requisições por minuto |

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}
```

## Próximo

<CardGroup cols={2}>
  <Card title="Criar nova instância" icon="plus" href="/pt/api/instance/create">
    Provisiona mais uma na sua conta, já com webhook, websocket e chatwoot configurados inline se quiser.
  </Card>

  <Card title="Conectar ao WhatsApp" icon="qrcode" href="/pt/api/instance/connect">
    Gere o QR code ou pairing code para vincular o número.
  </Card>
</CardGroup>