> ## 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 floating IP’s interfaces

> List attached interfaces using the canonical interface contract, with health and reason for this binding. Results are paginated by interface ID. Reading the floating IP authorizes this related collection.

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


## OpenAPI

````yaml /api-reference/specs/network.yaml get /v1/floating-ips/{floating_ip_id}/interfaces
openapi: 3.0.3
info:
  title: Basaltic Network API
  version: 1.0.0
  description: |
    The VPC surface — networks and subnets, interfaces, route tables,
    security groups, internet, NAT and egress-only gateways, and floating
    IPs.

    Relationship inputs use one reference field: UUID, CRN, or an exact name
    when the request supplies its required parent scope. Subnets and route
    tables are VPC-scoped; interfaces are subnet-scoped. Nested CRNs use
    vpc/<vpc>/subnet/<subnet>, vpc/<vpc>/route-table/<table>, and
    vpc/<vpc>/subnet/<subnet>/interface/<interface>. Names are immutable.
    Unknown request fields and list parameters are rejected.
    Supplied empty references are invalid and failed lookups never fall back
    to another reference kind. Every list accepts exact name and crn filters.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://network.{region}.basaltic.sh
    description: Regional API endpoint
    variables:
      region:
        default: sa-saopaulo-1
        description: Region code
security:
  - BearerAuth: []
paths:
  /v1/floating-ips/{floating_ip_id}/interfaces:
    get:
      tags:
        - Networking
      summary: List a floating IP’s interfaces
      description: >-
        List attached interfaces using the canonical interface contract, with
        health and reason for this binding. Results are paginated by interface
        ID. Reading the floating IP authorizes this related collection.
      operationId: listFloatingIpInterfaces
      parameters:
        - $ref: '#/components/parameters/FloatingIpId'
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
        - name: marker
          in: query
          schema:
            type: string
            format: uuid
        - name: crn
          in: query
          description: Exact interface CRN.
          schema:
            type: string
        - name: name
          in: query
          description: >-
            Interface names require subnet scope; this collection rejects bare
            name filters. Use crn instead.
          schema:
            type: string
      responses:
        '200':
          description: Attached interfaces
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FloatingIpInterfaceListResponse'
        '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'
      security:
        - BearerAuth: []
components:
  parameters:
    FloatingIpId:
      name: floating_ip_id
      in: path
      description: Floating IP ID
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    FloatingIpInterfaceListResponse:
      type: object
      required:
        - interfaces
        - meta
      properties:
        interfaces:
          type: array
          items:
            $ref: '#/components/schemas/FloatingIpInterface'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    FloatingIpInterface:
      description: An interface receiving the floating IP, with its attachment health.
      allOf:
        - $ref: '#/components/schemas/Interface'
        - type: object
          required:
            - health
            - reason
          properties:
            health:
              type: string
              enum:
                - unknown
                - healthy
                - unhealthy
              description: >
                What the platform knows about this member.


                `unknown` — nobody is checking. A member you attached yourself
                with no

                health check on the address reads this: you chose the moment of
                attach,

                and the platform has no signal about what runs inside the
                instance. It

                is advertised.


                `healthy` — the platform has evidence this member is up (and, if
                a

                health check is configured on the address, that the check is
                passing).


                `unhealthy` — the platform is waiting for that evidence and has
                not

                seen it, or a configured check is failing. The member keeps its
                place

                on the address and receives no traffic until it recovers.


                Without a health check this is liveness only — `healthy` means
                the guest

                came up, not that your service is listening. Configure
                `health_check` on

                the floating IP to add readiness on top of that.
              example: unknown
            reason:
              type: string
              enum:
                - unprobed
                - booting
                - probe_failed
                - passing
              description: >
                Why the member reads the `health` it does — so you can tell
                "your

                service is not answering" from "the guest has not booted yet".


                `unprobed` — nobody is checking (no health check,
                hand-attached).

                `booting` — the platform has not yet seen the guest come up.

                `probe_failed` — the configured health check is failing.

                `passing` — the guest is up and, if a check is configured, it
                passes.
              example: unprobed
            address_id:
              type: string
              format: uuid
              description: Target child address on the member interface.
    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
    Interface:
      type: object
      required:
        - id
        - crn
        - subnet
        - name
        - mac
        - tags
        - created_at
        - updated_at
        - attached_to
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        crn:
          type: string
          readOnly: true
          example: >-
            crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/public/interface/web-eth0
        subnet:
          allOf:
            - $ref: '#/components/schemas/ResourceRef'
          description: Subnet containing this interface.
          example:
            id: 550e8400-e29b-41d4-a716-446655440006
            crn: crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/private
            name: private
        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-eth0
        description:
          type: string
          example: Primary NIC for the web server
        mac:
          type: string
          example: aa:bb:cc:dd:ee:ff
        attached_to:
          anyOf:
            - $ref: '#/components/schemas/ResourceRef'
            - type: object
              nullable: true
              enum:
                - null
          description: >-
            Instance holding this interface, including a stopped instance. Null
            when unbound. Floating IP attachments are tracked separately.
          example:
            id: 550e8400-e29b-41d4-a716-446655440010
            crn: crn:compute:sa-saopaulo-1:my-account:instance/web-1
            name: web-1
        tags:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    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
  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.