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

> Devuelve las instancias visibles para el token, incluyendo status, perfil y un resumen de cada integración

**Auth:** `TokenAccount` o `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** sí

## Descripción

Cada item devuelto incluye el **status actual**, estado de conexión, datos de perfil y un resumen de las integraciones (webhook, websocket, chatwoot, proxy, settings, s3). Esta es la forma recomendada de inspeccionar el estado de una instancia.

El resultado depende del tipo de token:

* **TokenAccount**, devuelve **todas las instancias de tu cuenta**. Acepta el filtro `?instanceName=`.
* **TokenInstance**, devuelve **solo la instancia dueña del token** (el filtro se ignora).

## Ejemplos

### Listar todas las instancias de la cuenta

Sin filtro y usando el `TokenAccount`, devuelve todas las instancias visibles para la cuenta con status, perfil y resumen de integraciones de cada una.

<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 un nombre (recomendado para verificación de status)

Pasando `?instanceName=my-instance`, devuelve solo esa instancia, o **404** si no existe. Forma más económica de hacer polling al estado de la conexión después de llamar a `/connect`.

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

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

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

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

### Filtrar varios

Acepta múltiples nombres separados por coma en `?instanceName=sales,support`. Los nombres no existentes se ignoran silenciosamente, solo devuelve 404 cuando el filtro tiene un único nombre y este no existe.

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

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

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

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

### Ver datos de la propia instancia

Usando el `TokenInstance`, cualquier filtro se ignora y la respuesta trae solo la instancia dueña del token. Escenario típico para clientes que solo conocen el token de la instancia y quieren inspeccionar su propio 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>

## Respuesta exitosa

```json 200 OK theme={null}
{
  "success": true,
  "message": "1 Instance found",
  "instances": [
    {
      "id": "5e1d...",
      "name": "my-instance",
      "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://myapp.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>
  El campo `message` varía: `"1 Instance found"` cuando el total es 1, y `"<N> Instances found"` para otros valores.
</Info>

## Cabeceras

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

## Parámetros de consulta

<ParamField query="instanceName" type="string">
  Filtra por nombre. Acepta uno o varios nombres separados por coma (p. ej., `?instanceName=sales,support`). Solo funciona con TokenAccount.
</ParamField>

## Campos de respuesta

### `connection`

| Campo            | Tipo           | Descripción                                                                                   |
| ---------------- | -------------- | --------------------------------------------------------------------------------------------- |
| `state`          | string         | Estado real de la conexión whatsmeow (`connected`, `connecting`, `disconnected`, `loggedout`) |
| `numberJid`      | string \| null | JID del número (`5511999999999@s.whatsapp.net`) o `null` si nunca se conectó                  |
| `presenceStatus` | string         | `available`, `unavailable`, `composing`...                                                    |
| `displayStatus`  | string         | Status amigable para UI                                                                       |

### `profile`

| Campo          | Tipo    | Descripción                                   |
| -------------- | ------- | --------------------------------------------- |
| `name`         | string  | Nombre de display de WhatsApp                 |
| `pictureUrl`   | string  | URL de la foto de perfil (cache de whatsmeow) |
| `isBusiness`   | boolean | `true` si es WhatsApp Business                |
| `businessName` | string  | Nombre del Business (vacío si no es Business) |

### Integraciones

* `webhook`, webhook por defecto (label `default`). `enabled: false` significa sin webhook.
* `websocket`, `{ enabled, events, mediaBase64 }`. `enabled: false` significa que el WebSocket está apagado para la instancia.
* `chatwoot`, `{ enabled, status, bridgeIntegrationId, baseUrl, accountId, inboxName, apiToken, signMessages, ignoreGroups, startAsPending, reopenResolved }`. `enabled: false` significa que no hay integración Chatwoot activa (o que el módulo Chatwoot no está habilitado en el servidor). El `apiToken` viene en **plaintext** (misma exposición intencional que [`GET /api/chatwoot/list/:instance`](/es/api/chatwoot/info)), trátalo como sensible y solo aparece cuando hay integración. Los cuatro flags se devuelven **siempre** como `true`/`false` (las instancias sin Chatwoot reportan todos en `false` junto con `enabled: false`).
* `proxy`, proxy individual (no incluye el global del deploy).
* `settings`, flags de comportamiento (consulta [Actualizar settings](/es/api/instance/settings-update)).
* `s3`, configuración individual de almacenamiento S3.

## Reglas de filtrado

| Situación                                      | Comportamiento                                                |
| ---------------------------------------------- | ------------------------------------------------------------- |
| TokenAccount sin filtro                        | Devuelve todas las de la cuenta                               |
| TokenAccount con 1 nombre                      | Devuelve esa específica, o **404** si no existe               |
| TokenAccount con varios nombres                | Devuelve las que existen, los nombres inexistentes se ignoran |
| TokenAccount con filtro de solo comas/espacios | Devuelve lista vacía sin error                                |
| TokenInstance                                  | Ignora el filtro; devuelve solo su propia instancia           |

## Errores

| HTTP | `error.message`                         | Cuándo                            |
| :--: | --------------------------------------- | --------------------------------- |
|  401 | `Invalid token`                         | Token faltante o inválido         |
|  404 | `Instance not found`                    | Único nombre solicitado no existe |
|  429 | `Rate limit exceeded. Try again later.` | Más de 100 solicitudes por minuto |

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

## Siguiente

<CardGroup cols={2}>
  <Card title="Crear nueva instancia" icon="plus" href="/es/api/instance/create">
    Aprovisiona una más en tu cuenta, ya con webhook, websocket y chatwoot configurados inline si lo deseas.
  </Card>

  <Card title="Conectar a WhatsApp" icon="qrcode" href="/es/api/instance/connect">
    Genera el QR code o pairing code para vincular el número.
  </Card>
</CardGroup>