List Instances

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.

curl -X GET "https://ryzeapi.cloud/api/instance/list" \
  -H "token: $Token_Account"

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

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list",
    headers={
        "token": os.environ["Token_Account"]
    }
)

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

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.

curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=my-instance" \
  -H "token: $Token_Account"

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

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list?instanceName=my-instance",
    headers={
        "token": os.environ["Token_Account"]
    }
)

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

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.

curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=sales,support" \
  -H "token: $Token_Account"

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

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list?instanceName=sales,support",
    headers={
        "token": os.environ["Token_Account"]
    }
)

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

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.

curl -X GET "https://ryzeapi.cloud/api/instance/list" \
  -H "token: $Token_Instance"

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

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

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

Success response

200 OK

{
  "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
  }
}

The message field varies: "1 Instance found" when the total is 1, and "<N> Instances found" for other values.

Headers

string

required

TokenAccount or TokenInstance.

Query parameters

string

Filters by name. Accepts one or more names separated by comma (e.g., ?instanceName=sales,support). Only works with TokenAccount.

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), 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).
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

{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}

Create new instance

Provisions one more in your account, already with webhook, websocket, and chatwoot configured inline if you want.

Connect to WhatsApp

Generate the QR code or pairing code to link the number.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

List all instances of the account

Filter by single name (recommended for status checks)

Filter several

View own instance data

Success response

Headers

Query parameters

Response fields

`connection`

`profile`

Integrations

Filter rules

Errors

Next

Create new instance

Connect to WhatsApp

​Description

​Examples

​List all instances of the account

​Filter by single name (recommended for status checks)

​Filter several

​View own instance data

​Success response

​Headers

​Query parameters

​Response fields

​connection

​profile

​Integrations

​Filter rules

​Errors

​Next

Create new instance

Connect to WhatsApp

Description

Examples

List all instances of the account

Filter by single name (recommended for status checks)

Filter several

View own instance data

Success response

Headers

Query parameters

Response fields

`connection`

`profile`

Integrations

Filter rules

Errors

Next