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

# List a load balancer's instances

> List full compute instances belonging to this load balancer, with the same
filters, ordering and pagination as a compute instance pool. Each instance
includes its ResourceRefs and lifecycle fields, plus load balancer health
(`status`, `proxy_ok`, `last_seen`, `agent_version`) and optional retirement
details. The stable sequence number is in `metadata["basalt:pool:sequence_num"]`.
`status` describes proxy health; `current_state` describes the instance lifecycle.


<Info>
  Requires the IAM action **`loadbalancer:GetLoadBalancer`**. See [LOADBALANCER permissions](/loadbalancer/permissions) for the full list, what each one covers, and an example policy.
</Info>


## OpenAPI

````yaml /api-reference/specs/loadbalancer.yaml get /v1/load-balancers/{id}/instances
openapi: 3.0.3
info:
  title: Basaltic Load Balancer API
  version: 1.0.0
  description: >
    Request relationships accept syntax-classified references resolved within
    the caller account and region.

    Floating IP references accept UUID or CRN only; IP targets stay literal.

    Managed load balancers: listeners, target pools, health checks and the

    TLS certificates a listener terminates.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://loadbalancer.{region}.basaltic.sh
    description: Regional API endpoint
    variables:
      region:
        default: sa-saopaulo-1
        description: Region code
security:
  - BearerAuth: []
paths:
  /v1/load-balancers/{id}/instances:
    get:
      tags:
        - Load Balancers
      summary: List a load balancer's instances
      description: >
        List full compute instances belonging to this load balancer, with the
        same

        filters, ordering and pagination as a compute instance pool. Each
        instance

        includes its ResourceRefs and lifecycle fields, plus load balancer
        health

        (`status`, `proxy_ok`, `last_seen`, `agent_version`) and optional
        retirement

        details. The stable sequence number is in
        `metadata["basalt:pool:sequence_num"]`.

        `status` describes proxy health; `current_state` describes the instance
        lifecycle.
      operationId: listLoadBalancerInstances
      parameters:
        - $ref: '#/components/parameters/ComputeCRNFilter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
        - $ref: '#/components/parameters/ComputeNameFilter'
        - name: current_state
          in: query
          description: Filter by where the instances actually are.
          schema:
            $ref: '#/components/schemas/CurrentState'
        - name: flavor
          in: query
          description: Filter by regional flavor reference (UUID, CRN or exact name).
          schema:
            type: string
            example: a1b2c3d4-e5f6-4789-9abc-def012345678
        - name: image
          in: query
          description: >-
            Filter by image reference (UUID, CRN or name; images also accept
            name:version).
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440001
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: 4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadBalancerInstancesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    ComputeCRNFilter:
      name: crn
      in: query
      description: >-
        Exact resource CRN, intersected with all other filters before
        pagination. A foreign or mismatched CRN returns an empty page; malformed
        or empty CRNs return 400. Nested attachment lists filter the represented
        resource, not the binding.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: >-
        Maximum number of items to return. A value above the maximum is clamped
        to it rather than rejected, so a page shorter than the one you asked for
        is normal — page until `meta.has_more` is false, not until a page looks
        short.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
    Marker:
      name: marker
      in: query
      description: >-
        Opaque pagination cursor. Echo back the `meta.marker` value from the
        previous page to fetch the next one; do not construct or parse it. The
        token's internal form varies by endpoint (a resource ID, a timestamp, …)
        and is not guaranteed stable across releases.
      required: false
      schema:
        type: string
      example: 550e8400-e29b-41d4-a716-446655440000
    ComputeNameFilter:
      name: name
      in: query
      description: >-
        Exact, case-sensitive name. Empty values match no named resources.
        Instance NIC lists match interface names within the instance bindings;
        multiple interfaces with the same name may match. Floating IPs have no
        name identity and return an empty list for this filter.
      schema:
        type: string
  schemas:
    CurrentState:
      type: string
      description: |
        Where an instance actually is. The transitional states live here,
        not on desired_state — nobody asks for `stopping`.
      enum:
        - pending
        - building
        - running
        - stopping
        - stopped
        - rebooting
        - migrating
        - deleting
        - deleted
        - error
        - crashed
        - paused
        - suspended
    LoadBalancerInstancesResponse:
      type: object
      required:
        - instances
        - meta
      properties:
        instances:
          type: array
          items:
            $ref: '#/components/schemas/LoadBalancerInstance'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    LoadBalancerInstance:
      description: >
        A compute instance backing the load balancer, extended with proxy health
        and

        retirement details. During a resize, compare each instance's flavor.id
        with

        the load balancer's flavor.id. An extra instance may be present while
        the

        replacement starts serving and the old instance drains.
      allOf:
        - $ref: '#/components/schemas/Instance'
        - type: object
          required:
            - proxy_ok
            - status
          properties:
            retirement:
              $ref: '#/components/schemas/Retirement'
            status:
              type: string
              enum:
                - initializing
                - healthy
                - unhealthy
                - draining
              example: healthy
              description: >-
                Proxy health: initializing before the first report, healthy when
                the last report says the proxy is serving, unhealthy when it is
                down, and draining when the instance is retiring. See last_seen
                for the age of the last observation.
            proxy_ok:
              type: boolean
              description: Whether the proxy reported ready at the last health report
              example: true
            agent_version:
              type: string
              example: 1.4.2
            last_seen:
              type: string
              format: date-time
              description: Omitted when this instance has not reported yet
              example: '2026-01-15T09:31:00Z'
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items
          example: 150
        limit:
          type: integer
          description: Number of items per page
          example: 20
        marker:
          type: string
          description: >-
            Opaque cursor for the next page. Pass it back as the `marker` query
            parameter; treat it as a token, not a value to parse.
          example: 550e8400-e29b-41d4-a716-446655440000
        has_more:
          type: boolean
          description: Whether there are more items
          example: true
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Error code identifying the type of error
              example: INVALID_INPUT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Optional non-sensitive values for interpolation of localized
                errors, keyed by error code. Never present for server errors.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Request ID for debugging
              example: 550e8400-e29b-41d4-a716-446655440000
    Instance:
      type: object
      required:
        - faults
        - id
        - crn
        - name
        - flavor
        - image
        - iam_role
        - desired_state
        - current_state
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: 550e8400-e29b-41d4-a716-446655440000
        crn:
          type: string
          readOnly: true
          description: Cloud Resource Name
          example: crn:compute:sa-saopaulo-1:my-account:instance/web-01
        name:
          description: >-
            Resource names must not start with the literal crn: prefix or be
            UUIDs (canonical, compact, braced, or urn:uuid: forms, in either
            case).
          type: string
          example: web-server-01
        description:
          type: string
          example: Primary web server
        task_state:
          type: string
          nullable: true
          description: In-flight transition, if any; null when settled.
          example: null
        flavor:
          allOf:
            - $ref: '#/components/schemas/ResourceRef'
          description: >-
            Flavor identity. Every instance has a flavor; query the flavor
            resource for CPU and RAM.
          example:
            id: 550e8400-e29b-41d4-a716-446655440003
            crn: crn:compute:sa-saopaulo-1:platform:flavor/s1.small
            name: s1.small
        image:
          anyOf:
            - $ref: '#/components/schemas/ResourceRef'
            - type: object
              nullable: true
              enum:
                - null
          description: Pinned source image identity, or null for a volume-only boot.
          example:
            id: 550e8400-e29b-41d4-a716-446655440004
            crn: >-
              crn:compute:sa-saopaulo-1:platform:image/ubuntu/architecture/amd64/version/24.04
            name: ubuntu
        user_data:
          type: string
          description: Base64-encoded cloud-init user-data supplied at launch.
        iam_role:
          anyOf:
            - $ref: '#/components/schemas/ResourceRef'
            - type: object
              nullable: true
              enum:
                - null
          description: >-
            Attached IAM role identity, or null when no role is attached.
            Deleted roles retain their identity without name.
          example:
            id: 550e8400-e29b-41d4-a716-446655440005
            crn: crn:iam:::role/550e8400-e29b-41d4-a716-446655440005
            name: instance-role
        metadata:
          $ref: '#/components/schemas/Metadata'
        tags:
          $ref: '#/components/schemas/Tags'
        faults:
          type: array
          description: >-
            Active faults ordered by last_at descending, then internal history
            id descending for a stable tie-breaker. Healthy resources return [].
          items:
            $ref: '#/components/schemas/Fault'
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          readOnly: true
          example: '2024-01-15T10:30:00Z'
        launched_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          example: '2026-01-15T09:31:12Z'
        terminated_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          example: null
        desired_state:
          type: string
          enum:
            - running
            - stopped
            - deleted
          example: running
          description: |
            What was asked for. Only three values, because there are only three
            things you can ask an instance to be: Create/Start/Reboot ask for
            running, Stop for stopped, Delete for deleted.
        current_state:
          $ref: '#/components/schemas/CurrentState'
          example: running
          description: |
            Where the instance actually is. Read this one to answer "is it up" —
            the transitional states live here, not on desired_state, because
            nobody asks for `stopping`.

            desired_state=running with current_state=stopped is an instance that
            was asked to start and has not come up yet.
    Retirement:
      type: object
      readOnly: true
      required:
        - requested_at
        - drain_seconds
      properties:
        requested_at:
          type: string
          format: date-time
        drain_seconds:
          type: integer
          minimum: 30
          maximum: 3600
        agent_acknowledged_at:
          type: string
          format: date-time
        drain_until:
          type: string
          format: date-time
          description: Earliest deletion time; absent while withdrawal is pending.
    ResourceRef:
      type: object
      required:
        - id
        - crn
      properties:
        id:
          type: string
          format: uuid
          example: 288aa1e9-bbf5-5584-bce9-6a688f06d8a1
        crn:
          type: string
          example: crn:catalog::platform:country/288aa1e9-bbf5-5584-bce9-6a688f06d8a1
        name:
          type: string
          description: >-
            Display label at response time — the resource's name where it has
            one, otherwise its human label (an invoice number, an account
            display name). Absent when the target is gone. Not a lookup key.
          example: Brazil
    Metadata:
      type: object
      additionalProperties:
        type: string
      example:
        environment: production
        team: backend
    Tags:
      type: object
      additionalProperties:
        type: string
      example:
        environment: production
        team: backend
    Fault:
      type: object
      required:
        - code
        - severity
        - message
        - details
        - first_at
        - last_at
        - occurrences
      properties:
        code:
          type: string
          description: Stable machine-readable code owned by the reporting operation.
          example: BACKUP_FAILED
        severity:
          type: string
          enum:
            - error
            - warning
        message:
          type: string
          example: Backup upload failed.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: Structured context; legacy strings are preserved in legacy_text.
        first_at:
          type: string
          format: date-time
          description: First observation in this active occurrence series.
        last_at:
          type: string
          format: date-time
          description: Latest observation in this active occurrence series.
        occurrences:
          type: integer
          minimum: 1
          example: 1
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_INPUT
              message: Invalid request parameters
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ACCESS_DENIED
              message: You don't have permission to perform this action
              request_id: 550e8400-e29b-41d4-a716-446655440000
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
              request_id: 550e8400-e29b-41d4-a716-446655440000
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An internal error occurred
              request_id: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        An OAuth 2.0 bearer token, sent as `Authorization: Bearer <token>`.
        This is the recommended way to authenticate.

        Get one by exchanging a service account's access key pair at
        `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
        standard client-credentials grant, so any OAuth-aware library will
        obtain and refresh it for you.

        ```
        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```

        Tokens last an hour by default. The same access key pair is separately
        your AWS SigV4 credential for the S3-compatible object endpoint, which
        speaks nothing else.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.