List Instances

Retrieve information about one or more WhatsApp instances

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., [e-mail])

[].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

All Instances

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

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

curl -X GET "https://api.example.com/instance/fetchInstances?instanceId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "apikey: YOUR_API_KEY"

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

const response = await fetch('https://api.example.com/instance/fetchInstances', {
  method: 'GET',
  headers: {
    'apikey': 'YOUR_API_KEY'
  }
});

const instances = await response.json();
console.log(`Found ${instances.length} instances`);

instances.forEach(instance => {
  console.log(`${instance.instanceName}: ${instance.connectionStatus.state}`);
});

const instanceName = 'my-instance';
const response = await fetch(
  `https://api.example.com/instance/fetchInstances?instanceName=${instanceName}`,
  {
    method: 'GET',
    headers: {
      'apikey': 'YOUR_API_KEY'
    }
  }
);

const instances = await response.json();
if (instances.length > 0) {
  const instance = instances[0];
  console.log('Status:', instance.connectionStatus.state);
  console.log('Profile:', instance.profileName);
}

import requests

response = requests.get(
    'https://api.example.com/instance/fetchInstances',
    headers={'apikey': 'YOUR_API_KEY'}
)

instances = response.json()
print(f"Found {len(instances)} instances")

for instance in instances:
    print(f"{instance['instanceName']}: {instance['connectionStatus']['state']}")

import requests

instance_name = 'my-instance'
response = requests.get(
    f'https://api.example.com/instance/fetchInstances?instanceName={instance_name}',
    headers={'apikey': 'YOUR_API_KEY'}
)

instances = response.json()
if instances:
    instance = instances[0]
    print(f"Status: {instance['connectionStatus']['state']}")
    print(f"Profile: {instance['profileName']}")

<?php
$response = file_get_contents(
    'https://api.example.com/instance/fetchInstances',
    false,
    stream_context_create([
        'http' => [
            'method' => 'GET',
            'header' => 'apikey: YOUR_API_KEY'
        ]
    ])
);

$instances = json_decode($response, true);
echo "Found " . count($instances) . " instances\n";

foreach ($instances as $instance) {
    echo $instance['instanceName'] . ": " . 
         $instance['connectionStatus']['state'] . "\n";
}
?>

<?php
$instanceName = 'my-instance';
$response = file_get_contents(
    "https://api.example.com/instance/fetchInstances?instanceName={$instanceName}",
    false,
    stream_context_create([
        'http' => [
            'method' => 'GET',
            'header' => 'apikey: YOUR_API_KEY'
        ]
    ])
);

$instances = json_decode($response, true);
if (count($instances) > 0) {
    $instance = $instances[0];
    echo "Status: " . $instance['connectionStatus']['state'] . "\n";
    echo "Profile: " . $instance['profileName'] . "\n";
}
?>

Response Example

Success Response - Multiple Instances

[
  {
    "instanceName": "my-instance",
    "instanceId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "owner": "[e-mail]",
    "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": "[e-mail]",
    "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": "[e-mail]",
    "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 Type	Access Level
Global API Key	Returns 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.