Skip to main content

​
GET /instance/fetchInstances

Retrieve detailed information about your WhatsApp instances. You can fetch all instances, filter by specific instance name, or query by instance ID or phone number.

​
Authentication

This endpoint requires authentication via the apikey header. 
apikey: YOUR_API_KEY
If you use a global API key, you’ll see all instances. If you use an instance-specific token (the hash returned when creating an instance), you’ll only see instances associated with that token.

​
Query Parameters

​
instanceName
string
Filter results to a specific instance by name. Optional.
​
instanceId
string
Filter results by instance UUID. Optional.
​
number
string
Filter results by WhatsApp phone number. Optional.

​
Response

Returns an array of instance objects with detailed information:
​
[].instanceName
string
Name of the instance
​
[].instanceId
string
Unique instance identifier (UUID)
​
[].owner
string
Owner phone number in WhatsApp format (e.g., [email protected])
​
[].profileName
string
WhatsApp profile name
​
[].profilePicUrl
string
URL to profile picture
​
[].profileStatus
string
WhatsApp status message
​
[].status
string
Instance status: online, offline, connecting
​
[].connectionStatus
object
Detailed connection status
​
state
string
Connection state: open, close, connecting
​
statusReason
number
Numeric status reason code (when applicable)
​
[].integration
string
Integration type: WHATSAPP-BAILEYS, WHATSAPP-BUSINESS
​
[].serverUrl
string
Server URL for this instance
​
[].apikey
string
Instance-specific API key (hash)
​
[].createdAt
string
Instance creation timestamp (ISO 8601)
​
[].updatedAt
string
Last update timestamp (ISO 8601)

​
Examples

curl -X GET "https://api.example.com/instance/fetchInstances" \
  -H "apikey: YOUR_API_KEY"

​
Response Example

Success Response - Multiple Instances
[
  {
    "instanceName": "my-instance",
    "instanceId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "owner": "[email protected]",
    "profileName": "My Business",
    "profilePicUrl": "https://example.com/profile.jpg",
    "profileStatus": "Available 24/7",
    "status": "online",
    "connectionStatus": {
      "state": "open"
    },
    "integration": "WHATSAPP-BAILEYS",
    "serverUrl": "https://api.example.com",
    "apikey": "A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T14:25:00.000Z"
  },
  {
    "instanceName": "second-instance",
    "instanceId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "owner": "[email protected]",
    "profileName": "Support Team",
    "profilePicUrl": "https://example.com/support.jpg",
    "profileStatus": "How can we help?",
    "status": "online",
    "connectionStatus": {
      "state": "open"
    },
    "integration": "WHATSAPP-BAILEYS",
    "serverUrl": "https://api.example.com",
    "apikey": "B2C3D4E5-F6A7-4B8C-9D0E-1F2A3B4C5D6E",
    "createdAt": "2024-01-16T08:15:00.000Z",
    "updatedAt": "2024-01-16T12:45:00.000Z"
  }
]
Success Response - Single Instance
[
  {
    "instanceName": "my-instance",
    "instanceId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "owner": "[email protected]",
    "profileName": "My Business",
    "profilePicUrl": "https://example.com/profile.jpg",
    "profileStatus": "Available 24/7",
    "status": "online",
    "connectionStatus": {
      "state": "open"
    },
    "integration": "WHATSAPP-BAILEYS",
    "serverUrl": "https://api.example.com",
    "apikey": "A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T14:25:00.000Z"
  }
]
Error Response - Unauthorized
{
  "error": true,
  "message": "Unauthorized"
}
Empty Response - No Instances Found
[]

​
Connection Status States

The connectionStatus.state field indicates the current connection state:
  • open - Instance is connected and ready to send/receive messages
  • close - Instance is disconnected from WhatsApp
  • connecting - Instance is attempting to connect to WhatsApp

​
Error Handling

The API returns standard HTTP status codes:
  • 200 - Success (returns array, empty if no instances found)
  • 401 - Unauthorized (invalid API key or no permission to view instances)
  • 500 - Internal server error

​
Use Cases

Monitoring Dashboard: Use this endpoint to build a real-time dashboard showing the status of all your WhatsApp instances.
Health Checks: Poll this endpoint periodically to monitor instance connectivity and trigger alerts when instances go offline.
Instance Discovery: When you only have an instance name, use this endpoint to retrieve the full instance details including ID and API key.

​
Authentication Scopes

The response depends on your authentication level:
API Key TypeAccess Level
Global API KeyReturns all instances across your account
Instance Token (hash)Returns only instances associated with that token
Keep your API keys secure. The instance-specific token (apikey in response) grants full control over that instance.

Build docs developers (and LLMs) love

Get started for freeTalk to us