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

# List Instances

> Returns the instances visible to the token, including status, profile, and a summary of each integration

**Auth:** `TokenAccount` or `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotent:** yes

## Description

Each returned item includes the **current status**, connection state, profile data, and a summary of integrations (webhook, websocket, chatwoot, proxy, settings, s3). This is the recommended way to inspect the state of an instance.

The result depends on the token type:

* **TokenAccount**, returns **all instances of your account**. Accepts the `?instanceName=` filter.
* **TokenInstance**, returns **only the instance that owns the token** (filter is ignored).

## Examples

### List all instances of the account

Without a filter and using the `TokenAccount`, returns every instance visible to the account with status, profile, and integration summary for each.

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

### Filter by single name (recommended for status checks)

Passing `?instanceName=my-instance`, returns only that instance, or **404** if it doesn't exist. Cheapest way to poll the connection state after calling `/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>

### Filter several

Accepts multiple names separated by comma in `?instanceName=sales,support`. Non-existent names are ignored silently, only returns 404 when the filter has a single name and it doesn't exist.

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

### View own instance data

Using the `TokenInstance`, any filter is ignored and the response brings only the instance that owns the token. Typical scenario for clients that only know the instance token and want to inspect their own state.

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

## Success response

```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>
  The `message` field varies: `"1 Instance found"` when the total is 1, and `"<N> Instances found"` for other values.
</Info>

## Headers

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

## Query parameters

<ParamField query="instanceName" type="string">
  Filters by name. Accepts one or more names separated by comma (e.g., `?instanceName=sales,support`). Only works with TokenAccount.
</ParamField>

## Response fields

### `connection`

| Field            | Type           | Description                                                                                     |
| ---------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `state`          | string         | Real state of the whatsmeow connection (`connected`, `connecting`, `disconnected`, `loggedout`) |
| `numberJid`      | string \| null | JID of the number (`5511999999999@s.whatsapp.net`) or `null` if never connected                 |
| `presenceStatus` | string         | `available`, `unavailable`, `composing`...                                                      |
| `displayStatus`  | string         | UI-friendly status                                                                              |

### `profile`

| Field          | Type    | Description                           |
| -------------- | ------- | ------------------------------------- |
| `name`         | string  | WhatsApp display name                 |
| `pictureUrl`   | string  | Profile picture URL (whatsmeow cache) |
| `isBusiness`   | boolean | `true` if it's WhatsApp Business      |
| `businessName` | string  | Business name (empty if not Business) |

### Integrations

* `webhook`, default webhook (label `default`). `enabled: false` means no webhook.
* `websocket`, `{ enabled, events, mediaBase64 }`. `enabled: false` means WebSocket is off for the instance.
* `chatwoot`, `{ enabled, status, bridgeIntegrationId, baseUrl, accountId, inboxName, apiToken, signMessages, ignoreGroups, startAsPending, reopenResolved }`. `enabled: false` means no Chatwoot integration is on (or the Chatwoot module is not enabled on the server). The `apiToken` comes in **plaintext** (the same intentional exposure as in [`GET /api/chatwoot/list/:instance`](/en/api/chatwoot/info)), treat it as sensitive, and it only appears when there is an integration. The four flags are **always** returned as `true`/`false` (instances without Chatwoot report all of them `false` alongside `enabled: false`).
* `proxy`, individual proxy (does not include the deploy global one).
* `settings`, behavior flags (see [Update settings](/en/api/instance/settings-update)).
* `s3`, individual S3 storage config.

## Filter rules

| Situation                                      | Behavior                                                  |
| ---------------------------------------------- | --------------------------------------------------------- |
| TokenAccount with no filter                    | Returns all of the account                                |
| TokenAccount with 1 name                       | Returns that specific one, or **404** if it doesn't exist |
| TokenAccount with several names                | Returns those that exist, non-existent names are ignored  |
| TokenAccount with filter of only commas/spaces | Returns empty list with no error                          |
| TokenInstance                                  | Ignores filter; returns only its own instance             |

## Errors

| HTTP | `error.message`                         | When                                 |
| :--: | --------------------------------------- | ------------------------------------ |
|  401 | `Invalid token`                         | Token missing or invalid             |
|  404 | `Instance not found`                    | Single requested name does not exist |
|  429 | `Rate limit exceeded. Try again later.` | More than 100 requests per minute    |

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

## Next

<CardGroup cols={2}>
  <Card title="Create new instance" icon="plus" href="/en/api/instance/create">
    Provisions one more in your account, already with webhook, websocket, and chatwoot configured inline if you want.
  </Card>

  <Card title="Connect to WhatsApp" icon="qrcode" href="/en/api/instance/connect">
    Generate the QR code or pairing code to link the number.
  </Card>
</CardGroup>