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

# List Instances

> Retrieve all WhatsApp instances associated with your account with powerful filtering options.

List all WhatsApp instances associated with your authenticated account. Use filters to narrow down results by UUID, name, phone number, or status.

## Filtering Options

You can filter the list of instances using the following query parameters:

* `filter[uuid]` - Filter by instance UUID (exact match)
* `filter[name]` - Filter by instance name (partial match)
* `filter[phone]` - Filter by phone number (exact match)
* `filter[status]` - Filter by instance status

## Response Fields

Each instance in the response includes:

* `id` - Instance UUID
* `name` - Instance name
* `phone` - Phone number in E.164 format
* `service_type` - Service type (whatsapp)
* `status` - Current instance status
* `access_token` - Access token for the instance (null if not yet connected)
* `created_at` - Creation timestamp

## Example Use Cases

* Display all instances in your application dashboard
* Filter instances by status to show only active ones
* Search for a specific instance by name or phone number
* Monitor all instances created at a specific time

<Tip>
  Use the `filter[status]` parameter with value `WORKING` to get only active and ready instances.
</Tip>

## Instance Status Values

* `STOPPED`: Instance is stopped
* `STARTING`: Instance is starting up
* `WORKING`: Instance is running and ready
* `SCAN_QR_CODE`: Waiting for QR code scan
* `FAILED`: Instance failed to start
* `PENDING`: Awaiting server assignment


## OpenAPI

````yaml v1/api-reference/enterprise/enterprise-collection.json GET /instances
openapi: 3.1.0
info:
  version: v1.0
  title: Hypersender Enterprise API Docs
  description: >

    The Hypersender Enterprise API provides powerful management capabilities for
    WhatsApp instances.


    In this Docs you'll learn how to use and integrate Hypersender Enterprise
    API into your existing system/service or application using simple API
    endpoints.


    **What you can Do?**


    - Check instance health status

    - List all instances with filtering

    - Create new WhatsApp instances

    - Request new QR codes for authentication

    - Restart instances


    <hr />


    ## Servers (Endpoints)


    - Production (activated):
    [https://app.hypersender.com/api/whatsapp/v1](https://app.hypersender.com/api/whatsapp/v1)
servers:
  - url: https://app.hypersender.com/api/whatsapp/v1
    description: Production
security:
  - Authorization: []
paths:
  /instances:
    get:
      tags:
        - Instance Management
      summary: List Instances
      description: >-
        Lists all WhatsApp instances associated with the authenticated user's
        account.
      parameters:
        - name: Accept
          in: header
          description: application/json
          schema:
            type: string
            example: application/json
        - name: filter[uuid]
          in: query
          description: Filter by instance UUID
          required: false
          schema:
            type: string
        - name: filter[name]
          in: query
          description: Filter by instance name (partial match)
          required: false
          schema:
            type: string
        - name: filter[phone]
          in: query
          description: Filter by phone number
          required: false
          schema:
            type: string
        - name: filter[status]
          in: query
          description: Filter by instance status
          required: false
          schema:
            type: string
            enum:
              - STOPPED
              - STARTING
              - WORKING
              - SCAN_QR_CODE
              - FAILED
              - PENDING
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InstanceResponse'
              example:
                - id: fa3d01c4-1234-4c0d-a12f-df319b612f8c
                  name: MyInstanceName
                  phone: '+201234567890'
                  service_type: whatsapp
                  status: WORKING
                  access_token: 234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1
                  created_at: '2025-05-26T10:12:45'
                - id: c9a1dd76-5678-4f9d-9012-a5b78de100c3
                  name: SecondInstance
                  phone: '+201234567891'
                  service_type: whatsapp
                  status: SCAN_QR_CODE
                  access_token: null
                  created_at: '2025-05-25T15:30:22'
      security:
        - Authorization: []
components:
  schemas:
    InstanceResponse:
      type: object
      properties:
        id:
          type: string
          description: Instance UUID
          example: fa3d01c4-1234-4c0d-a12f-df319b612f8c
        name:
          type: string
          description: Instance name
          example: MyInstanceName
        phone:
          type: string
          description: Phone number in E.164 format
          example: '+201234567890'
        service_type:
          type: string
          description: Service type
          example: whatsapp
        status:
          type: string
          enum:
            - STOPPED
            - STARTING
            - WORKING
            - SCAN_QR_CODE
            - FAILED
            - PENDING
          description: Instance status
          example: WORKING
        access_token:
          type:
            - string
            - 'null'
          description: Access token for the instance
          example: 234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1
        created_at:
          type: string
          description: Creation timestamp
          example: '2025-05-26T10:12:45'
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication. Example: `Bearer
        234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1`

````