Skip to main content
GET
/
api
/
instance
/
list
List Instances
curl --request GET \
  --url https://api.example.com/api/instance/list \
  --header 'token: <token>'
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"
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"

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

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

​
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

​
token
string
required
TokenAccount or TokenInstance.

​
Query parameters

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

​
Response fields

​
connection

FieldTypeDescription
statestringReal state of the whatsmeow connection (connected, connecting, disconnected, loggedout)
numberJidstring | nullJID of the number (5511999999999@s.whatsapp.net) or null if never connected
presenceStatusstringavailable, unavailable, composing…
displayStatusstringUI-friendly status

​
profile

FieldTypeDescription
namestringWhatsApp display name
pictureUrlstringProfile picture URL (whatsmeow cache)
isBusinessbooleantrue if it’s WhatsApp Business
businessNamestringBusiness 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

SituationBehavior
TokenAccount with no filterReturns all of the account
TokenAccount with 1 nameReturns that specific one, or 404 if it doesn’t exist
TokenAccount with several namesReturns those that exist, non-existent names are ignored
TokenAccount with filter of only commas/spacesReturns empty list with no error
TokenInstanceIgnores filter; returns only its own instance

​
Errors

HTTPerror.messageWhen
401Invalid tokenToken missing or invalid
404Instance not foundSingle requested name does not exist
429Rate limit exceeded. Try again later.More than 100 requests per minute
{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}

​
Next

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.