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

# Listar as instâncias de um balanceador de carga

> Lista instâncias completas do compute pertencentes a este balanceador, com os mesmos filtros, ordenação e paginação de um pool de instâncias. Cada instância inclui ResourceRefs e campos do ciclo de vida, além da saúde do balanceador (`status`, `proxy_ok`, `last_seen`, `agent_version`) e detalhes opcionais de retirada. O número de sequência estável fica em `metadata["basalt:pool:sequence_num"]`. `status` descreve a saúde do proxy; `current_state` descreve o ciclo de vida da instância.


<Info>
  Requer a ação do IAM **`loadbalancer:GetLoadBalancer`**. Consulte [permissões de balanceadores de carga](/loadbalancer/permissions) para obter a lista completa, o que cada uma abrange e um exemplo de política.
</Info>


## OpenAPI

````yaml /pt/api-reference/specs/loadbalancer.yaml get /v1/load-balancers/{id}/instances
openapi: 3.0.3
info:
  title: API do Basaltic Load Balancer
  version: 1.0.0
  description: >
    Relações de solicitação aceitam referências classificadas por sintaxe
    resolvidas dentro da conta e região do chamador. Referências IP flutuantes
    aceitam somente UUID ou CRN; os alvos IP permanecem literais. Balanceadores
    de carga gerenciados: ouvintes, pools de destino, verificações de
    integridade e os certificados TLS que um ouvinte encerra.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://loadbalancer.{region}.basaltic.sh
    description: Endpoint de API regional
    variables:
      region:
        default: sa-saopaulo-1
        description: Código de região
security:
  - BearerAuth: []
paths:
  /v1/load-balancers/{id}/instances:
    get:
      tags:
        - Load Balancers
      summary: Listar as instâncias de um balanceador de carga
      description: >
        Lista instâncias completas do compute pertencentes a este balanceador,
        com os mesmos filtros, ordenação e paginação de um pool de instâncias.
        Cada instância inclui ResourceRefs e campos do ciclo de vida, além da
        saúde do balanceador (`status`, `proxy_ok`, `last_seen`,
        `agent_version`) e detalhes opcionais de retirada. O número de sequência
        estável fica em `metadata["basalt:pool:sequence_num"]`. `status`
        descreve a saúde do proxy; `current_state` descreve o ciclo de vida da
        instância.
      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: Filtre por onde as instâncias estão realmente.
          schema:
            $ref: '#/components/schemas/CurrentState'
        - name: flavor
          in: query
          description: >-
            Filtrar por referência de tipo de instância regional (UUID, CRN ou
            nome exato).
          schema:
            type: string
            example: a1b2c3d4-e5f6-4789-9abc-def012345678
        - name: image
          in: query
          description: >-
            Filtrar por referência de imagem (UUID, CRN ou nome; imagens também
            aceitam nome:versão).
          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: >-
        CRN exato do recurso, intersetado com todos os outros filtros antes da
        paginação. Um CRN estrangeiro ou não correspondido retorna uma página
        vazia; CRNs malformados ou vazios retornam 400. As listas de anexos
        aninhadas filtram o recurso representado, não a vinculação.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: >-
        Número máximo de itens a devolver. Um valor acima do máximo é fixado ao
        invés de rejeitado, então uma página mais curta do que a que você pediu
        é normal — page until `meta.has_more` é false, não até que uma página
        pareça curta.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
    Marker:
      name: marker
      in: query
      description: >-
        Cursor de paginação opaco. Echo back o valor `meta.marker` da página
        anterior para buscar a próxima; não construa ou analise-o. A forma
        interna do token varia de acordo com o endpoint (um ID de recurso, um
        carimbo de data/hora, etc.) e não é garantida a estabilidade entre
        versões.
      required: false
      schema:
        type: string
      example: 550e8400-e29b-41d4-a716-446655440000
    ComputeNameFilter:
      name: name
      in: query
      description: >-
        Exato, nome sensível a maiúsculas. Valores vazios não correspondem a
        nenhum recurso nomeado. As listas de NICs de instância correspondem aos
        nomes de interface dentro das ligações de instância; várias interfaces
        com o mesmo nome podem corresponder. Os IPs flutuantes não têm
        identidade de nome e retornam uma lista vazia para esse filtro.
      schema:
        type: string
  schemas:
    CurrentState:
      type: string
      description: >
        Os estados de transição vivem aqui, não em desired\_state — ninguém pede
        para eles serem criados. `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: >
        Uma instância do compute que atende o balanceador de carga, com saúde do
        proxy e detalhes de retirada. Durante um redimensionamento, compare
        flavor.id de cada instância com flavor.id do balanceador. Uma instância
        extra pode aparecer enquanto a substituta começa a servir e a antiga
        drena.
      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: >-
                Saúde do proxy: initializing antes do primeiro relatório,
                healthy quando o último relatório indica que o proxy está
                servindo, unhealthy quando está fora do ar e draining quando a
                instância está sendo retirada. Veja last_seen para a idade da
                última observação.
            proxy_ok:
              type: boolean
              description: >-
                Se o proxy foi relatado pronto no último relatório de
                integridade
              example: true
            agent_version:
              type: string
              example: 1.4.2
            last_seen:
              type: string
              format: date-time
              description: Omitido quando esta instância ainda não enviou um relatório
              example: '2026-01-15T09:31:00Z'
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Número total de itens
          example: 150
        limit:
          type: integer
          description: Número de itens por página
          example: 20
        marker:
          type: string
          description: >-
            Cursor opaco para a próxima página. Passe-o de volta como o
            parâmetro de consulta `marker`; trate-o como um token, não um valor
            para analisar.
          example: 550e8400-e29b-41d4-a716-446655440000
        has_more:
          type: boolean
          description: Se há mais itens
          example: true
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Código de erro identificando o tipo de erro
              example: INVALID_INPUT
            message:
              type: string
              description: Mensagem de erro legível pelo ser humano
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Valores não sensíveis opcionais para interpolação de erros
                localizados, codificados por código de erro. Nunca presente para
                erros de servidor.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Solicitar ID para depuração
              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: Nome do recurso da nuvem
          example: crn:compute:sa-saopaulo-1:my-account:instance/web-01
        name:
          description: >-
            Os nomes de recursos não devem começar com o prefixo literal crn: ou
            ser UUIDs (formas canônicas, compactas, entre colchetes ou
            urn:uuid:, em qualquer caso).
          type: string
          example: web-server-01
        description:
          type: string
          example: Primary web server
        task_state:
          type: string
          nullable: true
          description: Transição em andamento, se houver; nulo quando resolvido.
          example: null
        flavor:
          allOf:
            - $ref: '#/components/schemas/ResourceRef'
          description: >-
            Identidade do flavor. Toda instância tem um flavor; consulte o
            recurso flavor para obter CPU e 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: >-
            Identidade fixada da imagem de origem, ou null para inicialização
            apenas por volume.
          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: >-
            Dados de usuário cloud-init codificados em Base64 fornecidos no
            lançamento.
        iam_role:
          anyOf:
            - $ref: '#/components/schemas/ResourceRef'
            - type: object
              nullable: true
              enum:
                - null
          description: >-
            Identidade da função IAM vinculada, ou null quando não há função
            vinculada. Funções excluídas mantêm sua identidade sem 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: >-
            Falhas ativas ordenadas por last_at descendente, em seguida, o
            histórico interno id descendente para um desempate estável. Recursos
            saudáveis retornam [].
          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: >
            O que foi pedido. Apenas três valores, porque há apenas três coisas
            que você pode pedir para uma instância ser: Create/Start/Reboot para
            execução, Stop para parada, Delete para exclusão.
        current_state:
          $ref: '#/components/schemas/CurrentState'
          example: running
          description: >
            Leia este para responder "is it up" — os estados de transição vivem
            aqui, não em desired\_state, porque ninguém pede para eles serem
            criados. `stopping`.


            desired_state=running com current_state=stopped é uma instância que
            foi solicitada para iniciar e ainda não foi exibida.
    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: >-
            Tempo de exclusão mais cedo; ausente enquanto a retirada está
            pendente.
    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: >-
            Rótulo no momento da resposta: o nome do recurso, quando houver, ou
            seu rótulo legível (número de fatura, nome de exibição da conta).
            Ausente quando o destino não existe mais. Não é uma chave de
            consulta.
          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: >-
            Código estável legível por máquina pertencente à operação de
            relatório.
          example: BACKUP_FAILED
        severity:
          type: string
          enum:
            - error
            - warning
        message:
          type: string
          example: Backup upload failed.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Contexto estruturado; cadeias de caracteres legadas são preservadas
            em legacy_text.
        first_at:
          type: string
          format: date-time
          description: Primeira observação nesta série de ocorrências ativas.
        last_at:
          type: string
          format: date-time
          description: Última observação nesta série de ocorrências ativas.
        occurrences:
          type: integer
          minimum: 1
          example: 1
  responses:
    BadRequest:
      description: Parâmetros de solicitação inválidos
      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: Autenticação necessária ou token inválido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Permissões insuficientes
      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: Página não encontrada
      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: Erro interno do servidor
      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: >+
        Um token bearer OAuth 2.0, enviado como `Authorization: Bearer <token>`.
        Esta é a forma recomendada de autenticação.


        Obtenha o token trocando o par de chaves de acesso de uma conta de
        serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`.
        Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis
        com OAuth podem obter e renovar o token para você.


        ```

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


        Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso
        também serve como credencial AWS SigV4 para o endpoint de objetos
        compatível com S3, que aceita somente esse método de autenticação.


````

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