> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/EvolutionAPI/evolution-api/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
apikey: YOUR_API_KEY
```

<Note>
  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.
</Note>

### Query Parameters

<ParamField query="instanceName" type="string">
  Filter results to a specific instance by name. Optional.
</ParamField>

<ParamField query="instanceId" type="string">
  Filter results by instance UUID. Optional.
</ParamField>

<ParamField query="number" type="string">
  Filter results by WhatsApp phone number. Optional.
</ParamField>

### Response

Returns an array of instance objects with detailed information:

<ResponseField name="[].instanceName" type="string">
  Name of the instance
</ResponseField>

<ResponseField name="[].instanceId" type="string">
  Unique instance identifier (UUID)
</ResponseField>

<ResponseField name="[].owner" type="string">
  Owner phone number in WhatsApp format (e.g., `5511999999999@s.whatsapp.net`)
</ResponseField>

<ResponseField name="[].profileName" type="string">
  WhatsApp profile name
</ResponseField>

<ResponseField name="[].profilePicUrl" type="string">
  URL to profile picture
</ResponseField>

<ResponseField name="[].profileStatus" type="string">
  WhatsApp status message
</ResponseField>

<ResponseField name="[].status" type="string">
  Instance status: `online`, `offline`, `connecting`
</ResponseField>

<ResponseField name="[].connectionStatus" type="object">
  Detailed connection status

  <ResponseField name="state" type="string">
    Connection state: `open`, `close`, `connecting`
  </ResponseField>

  <ResponseField name="statusReason" type="number">
    Numeric status reason code (when applicable)
  </ResponseField>
</ResponseField>

<ResponseField name="[].integration" type="string">
  Integration type: `WHATSAPP-BAILEYS`, `WHATSAPP-BUSINESS`
</ResponseField>

<ResponseField name="[].serverUrl" type="string">
  Server URL for this instance
</ResponseField>

<ResponseField name="[].apikey" type="string">
  Instance-specific API key (hash)
</ResponseField>

<ResponseField name="[].createdAt" type="string">
  Instance creation timestamp (ISO 8601)
</ResponseField>

<ResponseField name="[].updatedAt" type="string">
  Last update timestamp (ISO 8601)
</ResponseField>

### Examples

<CodeGroup>
  ```bash All Instances theme={null}
  curl -X GET "https://api.example.com/instance/fetchInstances" \
    -H "apikey: YOUR_API_KEY"
  ```

  ```bash Specific Instance theme={null}
  curl -X GET "https://api.example.com/instance/fetchInstances?instanceName=my-instance" \
    -H "apikey: YOUR_API_KEY"
  ```

  ```bash By Instance ID theme={null}
  curl -X GET "https://api.example.com/instance/fetchInstances?instanceId=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
    -H "apikey: YOUR_API_KEY"
  ```

  ```bash By Phone Number theme={null}
  curl -X GET "https://api.example.com/instance/fetchInstances?number=5511999999999" \
    -H "apikey: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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}`);
  });
  ```

  ```javascript JavaScript - Filter by Name theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```python Python - Filter by Name theme={null}
  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 PHP theme={null}
  <?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 PHP - Filter by Name theme={null}
  <?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";
  }
  ?>
  ```
</CodeGroup>

### Response Example

```json Success Response - Multiple Instances theme={null}
[
  {
    "instanceName": "my-instance",
    "instanceId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "owner": "5511999999999@s.whatsapp.net",
    "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": "5511888888888@s.whatsapp.net",
    "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"
  }
]
```

```json Success Response - Single Instance theme={null}
[
  {
    "instanceName": "my-instance",
    "instanceId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "owner": "5511999999999@s.whatsapp.net",
    "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"
  }
]
```

```json Error Response - Unauthorized theme={null}
{
  "error": true,
  "message": "Unauthorized"
}
```

```json Empty Response - No Instances Found theme={null}
[]
```

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

<Note>
  **Monitoring Dashboard**: Use this endpoint to build a real-time dashboard showing the status of all your WhatsApp instances.
</Note>

<Note>
  **Health Checks**: Poll this endpoint periodically to monitor instance connectivity and trigger alerts when instances go offline.
</Note>

<Note>
  **Instance Discovery**: When you only have an instance name, use this endpoint to retrieve the full instance details including ID and API key.
</Note>

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

<Warning>
  Keep your API keys secure. The instance-specific token (`apikey` in response) grants full control over that instance.
</Warning>