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

# List servers

> ### Overview

Lists servers in the current team without pagination or filters. To list another team's servers, use an API key for that team. Add `?include=user` to include the account that owns each server. Otherwise, that field is omitted.

### Permissions

Requires the `server.read` (View servers) permission for the selected team. Resources outside that team return 404.



## OpenAPI

````yaml https://console.advinservers.com/docs/openapi.json get /servers
openapi: 3.1.0
info:
  title: API reference
  version: 1.0.0
  description: >-
    Use this API to manage your team's servers, networks, backups, and other
    resources.


    ## Authentication


    Create an API key under **API Keys** and send it as a bearer token with
    every request:


    ```

    Authorization: Bearer {YOUR_API_KEY}

    Accept: application/json

    ```


    Copy the key when you create it. It cannot be shown again. Revoking a key
    takes effect immediately.


    ## Permissions


    Give each key only the permissions it needs. Every endpoint lists the
    required permission.


    Permissions cover servers and other resources in the key's team.


    ## Team scope


    A key can access resources in the team selected when it was created. This
    includes servers,

    snapshots, backups, firewall groups, images, SSH keys, scripts, networks and
    addresses.

    Resources in other teams return `404 Not Found`. Create a separate key for
    each team.


    The key determines the team for every request. Legacy keys that had no team
    are assigned

    to the account's first owned team.


    ## Actions that need the panel


    API keys cannot do the following, even with every permission. Sign in to the
    panel in a

    browser to do them:


    - Create, edit or revoke API keys

    - Edit the IP groups that restrict API keys

    - End signed-in sessions

    - Change two-factor authentication

    - Change the account's email address

    - Accept or decline team invitations

    - Switch or leave a team


    This keeps a leaked key from widening its own access or locking you out of
    your account.


    ## Source IP restrictions


    A key can be restricted to one or more IP groups. Requests from other
    addresses are rejected.


    ## Requests and responses


    Each endpoint lists its path, query, header, and body parameters. Examples
    use fictional data.


    Single records use JSON objects. Collections use JSON arrays unless the
    endpoint supports pagination. Timestamps use ISO 8601 in UTC.


    Error responses include `message`. Validation errors also include an
    `errors` object for each field. Each endpoint lists its status codes.


    ## Audit log


    Every API request, including reads, is recorded in the account audit log
    with the key that made it.
servers:
  - url: https://console.advinservers.com/api/v1/client
security:
  - http: []
tags:
  - name: Account
    description: Billing contact details and account setup progress.
  - name: Account activity
    description: Actions performed in the current team by people and API keys.
  - name: Servers
    description: >-
      Order and list servers, read their state and resource use, open a console,
      and control power.
  - name: Server settings
    description: >-
      Rename a server, rebuild it, and change its hardware, media, resolvers and
      credentials.
  - name: Backups
    description: Scheduled server copies stored separately from the server.
  - name: Snapshots
    description: >-
      Take, restore and move server snapshots. Snapshots are kept in snapshot
      storage that the team buys by the GiB.
  - name: Firewall groups
    description: Reusable sets of firewall rules, and the servers they apply to.
  - name: IP groups
    description: Reusable source address lists for firewall rules.
  - name: Server firewall
    description: >-
      Read default traffic policies and rules managed outside your firewall
      groups.
  - name: IP addresses
    description: Manage floating IPs and server address assignments.
  - name: Private networks
    description: Connect servers over a private network in the same location.
  - name: Reverse DNS
    description: Set the hostnames returned by IP address lookups.
  - name: DDoS protection
    description: Configure attack filtering for server addresses.
  - name: Bandwidth
    description: Buy extra bandwidth and share it between servers or location pools.
  - name: SSH keys
    description: Public keys the account can install on a server when it is built.
  - name: Setup scripts
    description: Scripts the account can run on a server when it is built.
  - name: ISO images
    description: ISO images you have downloaded, and the servers they are mounted on.
  - name: Server upgrades
    description: Change an existing server's plan.
  - name: Checkout
    description: Choose a payment method and pay for a purchase.
  - name: Invoices
    description: View and pay account invoices.
  - name: Billing
    description: Manage service renewals, payment methods and account credit.
  - name: Transfers
    description: Move resources between teams or transfer ownership.
  - name: Teams
    description: Manage the team assigned to your API key.
  - name: Team members
    description: Invite people and manage their team access.
  - name: Team roles
    description: Define the permissions granted to team members.
  - name: Team activity
    description: View actions performed in a team.
  - name: Support tickets
    description: >-
      Open, read, reply to and close support tickets. Tickets belong to the
      account holder and are not shared with team members.
paths:
  /servers:
    get:
      tags:
        - Servers
      summary: List servers
      description: >-
        ### Overview


        Lists servers in the current team without pagination or filters. To list
        another team's servers, use an API key for that team. Add
        `?include=user` to include the account that owns each server. Otherwise,
        that field is omitted.


        ### Permissions


        Requires the `server.read` (View servers) permission for the selected
        team. Resources outside that team return 404.
      operationId: index.list
      responses:
        '200':
          description: The whole set, as a JSON array. There is no envelope and no paging.
          content:
            application/json:
              schema:
                type: array
                examples:
                  - - id: ecc6f4f1
                      uuid: ecc6f4f1-c89b-4dce-a20b-a330641c5b0b
                      hostname: lambda-core.blackmesa.example.com
                      name: lambda-core
                      description: Lambda Complex test chamber telemetry
                      status: null
                      suspension_reason: null
                      power_state: running
                      windows: false
                      template_name: Ubuntu 24.04
                      template_icon_url: https://img.icons8.com/color/48/ubuntu.png
                      custom_icon_url: null
                      default_icon_url: https://img.icons8.com/color/48/ubuntu.png
                      created_at: '2026-03-02T19:14:36.000000Z'
                      usages:
                        bandwidth: 500000000000
                        actual_bandwidth: 500000000000
                        rx: 200000000000
                        tx: 300000000000
                      limits:
                        cpu: 4
                        memory: 4294967296
                        disk: 85899345920
                        hdd_disk: null
                        snapshots: 2
                        backups: 2
                        bandwidth: 5497558138880
                        addresses:
                          ipv4:
                            - id: 58213
                              address_pool_id: 4
                              server_id: 4821
                              user_id: null
                              type: ipv4
                              is_primary: true
                              address: 203.0.113.24
                              cidr: 24
                              gateway: 203.0.113.1
                              mac_address: 52:54:00:3a:7c:91
                              onlink: null
                              floating_ip_uuid: null
                            - id: 58391
                              address_pool_id: 4
                              server_id: 4821
                              user_id: null
                              type: ipv4
                              is_primary: false
                              address: 203.0.113.88
                              cidr: 24
                              gateway: 203.0.113.1
                              mac_address: 52:54:00:3a:7c:91
                              onlink: null
                              floating_ip_uuid: null
                          ipv6:
                            - id: 58214
                              address_pool_id: 5
                              server_id: 4821
                              user_id: null
                              type: ipv6
                              is_primary: false
                              address: 2001:db8:4b2:18::1
                              cidr: 64
                              gateway: 2001:db8:4b2::1
                              mac_address: 52:54:00:3a:7c:91
                              onlink: 2001:db8:4b2::18
                              floating_ip_uuid: null
                        mac_address: 52:54:00:3a:7c:91
                        effective_bandwidth: 5497558138880
                        bandwidth_blocks: 0
                        plan_bandwidth: 5497558138880
                      internal_id: 4821
                      restoration_progress: null
                      installation_progress: null
                      install_failed_at: null
                      cpu_throttle: null
                      bandwidth: null
                      provisioning_scripts_supported: true
                      snapshots_supported: true
                      maintenance: null
                      maintenance_events: []
                      location: Kansas City, MO
                      product_group_name: Standard VPS
                items:
                  $ref: '#/components/schemas/ServerData'
        '401':
          description: >-
            The key was missing, malformed, revoked, or belongs to an account
            that no longer exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Unauthenticated.
                required:
                  - message
        '403':
          description: >-
            Access denied. Check the key's team, permissions and allowed IP
            addresses. Some actions, such as managing API keys, require a
            browser session. The response message explains the reason.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - >-
                        This API key is not allowed to do that in this team. It
                        needs the "snapshot.delete" permission.
                required:
                  - message
        '429':
          description: >-
            Too many requests. The `Retry-After` header says how many seconds to
            wait. Limits are per account, so several keys on one account share
            them.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Too Many Attempts.
                required:
                  - message
components:
  schemas:
    ServerData:
      type: object
      description: A server and its current configuration and status.
      examples:
        - id: ecc6f4f1
          uuid: ecc6f4f1-c89b-4dce-a20b-a330641c5b0b
          hostname: lambda-core.blackmesa.example.com
          name: lambda-core
          description: Lambda Complex test chamber telemetry
          status: null
          suspension_reason: null
          power_state: running
          windows: false
          template_name: Ubuntu 24.04
          template_icon_url: https://img.icons8.com/color/48/ubuntu.png
          custom_icon_url: null
          default_icon_url: https://img.icons8.com/color/48/ubuntu.png
          created_at: '2026-03-02T19:14:36.000000Z'
          usages:
            bandwidth: 500000000000
            actual_bandwidth: 500000000000
            rx: 200000000000
            tx: 300000000000
          limits:
            cpu: 4
            memory: 4294967296
            disk: 85899345920
            hdd_disk: null
            snapshots: 2
            backups: 2
            bandwidth: 5497558138880
            addresses:
              ipv4:
                - id: 58213
                  address_pool_id: 4
                  server_id: 4821
                  user_id: null
                  type: ipv4
                  is_primary: true
                  address: 203.0.113.24
                  cidr: 24
                  gateway: 203.0.113.1
                  mac_address: 52:54:00:3a:7c:91
                  onlink: null
                  floating_ip_uuid: null
                - id: 58391
                  address_pool_id: 4
                  server_id: 4821
                  user_id: null
                  type: ipv4
                  is_primary: false
                  address: 203.0.113.88
                  cidr: 24
                  gateway: 203.0.113.1
                  mac_address: 52:54:00:3a:7c:91
                  onlink: null
                  floating_ip_uuid: null
              ipv6:
                - id: 58214
                  address_pool_id: 5
                  server_id: 4821
                  user_id: null
                  type: ipv6
                  is_primary: false
                  address: 2001:db8:4b2:18::1
                  cidr: 64
                  gateway: 2001:db8:4b2::1
                  mac_address: 52:54:00:3a:7c:91
                  onlink: 2001:db8:4b2::18
                  floating_ip_uuid: null
            mac_address: 52:54:00:3a:7c:91
            effective_bandwidth: 5497558138880
            bandwidth_blocks: 0
            plan_bandwidth: 5497558138880
          internal_id: 4821
          restoration_progress: null
          installation_progress: null
          install_failed_at: null
          cpu_throttle: null
          bandwidth: null
          provisioning_scripts_supported: true
          snapshots_supported: true
          maintenance: null
          maintenance_events: []
          location: Kansas City, MO
          product_group_name: Standard VPS
      properties:
        id:
          type: string
          description: The short uuid. This is what every customer-facing URL is keyed by.
          examples:
            - ecc6f4f1
        uuid:
          type: string
          description: The uuid UUID.
          examples:
            - ecc6f4f1-c89b-4dce-a20b-a330641c5b0b
        hostname:
          type: string
          description: The fully qualified hostname.
          examples:
            - lambda-core.blackmesa.example.com
        name:
          type: string
          description: The name shown to customers.
          examples:
            - lambda-core
        description:
          type:
            - string
            - 'null'
          description: An optional description shown to customers.
          examples:
            - Lambda Complex test chamber telemetry
        status:
          type:
            - string
            - 'null'
          description: >-
            A pending server operation, or null when there is none. `starting`
            and `stopping` clear when the power command finishes.
          enum:
            - installing
            - install_failed
            - suspended
            - restoring_backup
            - restoring_snapshot
            - snapshotting
            - deleting
            - deletion_failed
            - upgrading
            - migrating
            - starting
            - stopping
            - null
          examples:
            - null
        suspension_reason:
          type:
            - string
            - 'null'
          description: >-
            Why the hold above is on, in the words of whoever put it on, or null
            where no reason was given. Only ever set alongside `suspended`: it
            is cleared when the suspension is lifted. Show it to the customer -
            it is written for them, and it is the difference between a machine
            that says it is suspended and one that says what to do about it.
          examples:
            - null
        power_state:
          type:
            - string
            - 'null'
          description: The value of `power_state`.
          enum:
            - running
            - stopped
            - paused
            - null
          examples:
            - running
        windows:
          type: boolean
          description: The value of `windows`.
          examples:
            - false
        template_name:
          type:
            - string
            - 'null'
          description: The value of `template_name`.
          examples:
            - Ubuntu 24.04
        template_icon_url:
          type:
            - string
            - 'null'
          description: >-
            The icon actually in force: the customer's own pick where they have
            made one, otherwise the artwork snapshotted from the template.
          examples:
            - https://img.icons8.com/color/48/ubuntu.png
        custom_icon_url:
          type:
            - string
            - 'null'
          description: The raw override, so a form can tell a pick from a default.
          examples:
            - null
        default_icon_url:
          type:
            - string
            - 'null'
          description: What the icon falls back to if that override is cleared.
          examples:
            - https://img.icons8.com/color/48/ubuntu.png
        created_at:
          type: string
          description: The date and time for created at, in UTC.
          examples:
            - '2026-03-02T19:14:36.000000Z'
        usages:
          $ref: '#/components/schemas/ServerUsagesData'
          description: The value of `usages`.
          examples:
            - bandwidth: 500000000000
              actual_bandwidth: 500000000000
              rx: 200000000000
              tx: 300000000000
        limits:
          $ref: '#/components/schemas/ServerLimitsData'
          description: The value of `limits`.
          examples:
            - cpu: 4
              memory: 4294967296
              disk: 85899345920
              hdd_disk: null
              snapshots: 2
              backups: 2
              bandwidth: 5497558138880
              addresses:
                ipv4:
                  - id: 58213
                    address_pool_id: 4
                    server_id: 4821
                    user_id: null
                    type: ipv4
                    is_primary: true
                    address: 203.0.113.24
                    cidr: 24
                    gateway: 203.0.113.1
                    mac_address: 52:54:00:3a:7c:91
                    onlink: null
                    floating_ip_uuid: null
                  - id: 58391
                    address_pool_id: 4
                    server_id: 4821
                    user_id: null
                    type: ipv4
                    is_primary: false
                    address: 203.0.113.88
                    cidr: 24
                    gateway: 203.0.113.1
                    mac_address: 52:54:00:3a:7c:91
                    onlink: null
                    floating_ip_uuid: null
                ipv6:
                  - id: 58214
                    address_pool_id: 5
                    server_id: 4821
                    user_id: null
                    type: ipv6
                    is_primary: false
                    address: 2001:db8:4b2:18::1
                    cidr: 64
                    gateway: 2001:db8:4b2::1
                    mac_address: 52:54:00:3a:7c:91
                    onlink: 2001:db8:4b2::18
                    floating_ip_uuid: null
              mac_address: 52:54:00:3a:7c:91
              effective_bandwidth: 5497558138880
              bandwidth_blocks: 0
              plan_bandwidth: 5497558138880
        internal_id:
          type: integer
          description: The primary key. See the note on `id` above.
          examples:
            - 4821
        restoration_progress:
          type:
            - integer
            - 'null'
          description: The value of `restoration_progress`.
          examples:
            - null
        installation_progress:
          type:
            - integer
            - 'null'
          description: The value of `installation_progress`.
          examples:
            - null
        install_failed_at:
          type:
            - string
            - 'null'
          description: >-
            Set only while the last install or rebuild is still an unread
            failure: cleared by the next attempt, and by the customer dismissing
            the notice it draws.
          examples:
            - null
        cpu_throttle:
          description: The value of `cpu_throttle`.
          examples:
            - null
          anyOf:
            - $ref: '#/components/schemas/ServerCpuThrottleData'
            - type: 'null'
        bandwidth:
          description: >-
            What the server's transfer really looks like once purchased blocks
            and pooling exist. Null, like `cpu_throttle` above it, whenever the
            plan's own allowance is the whole story.
          examples:
            - null
          anyOf:
            - $ref: '#/components/schemas/ServerBandwidthData'
            - type: 'null'
        provisioning_scripts_supported:
          type: boolean
          description: The value of `provisioning_scripts_supported`.
          examples:
            - true
        snapshots_supported:
          type: boolean
          description: Whether snapshot storage is available in this server's location.
          examples:
            - true
        maintenance:
          description: >-
            Null unless maintenance that affects this server is planned or under
            way.
          examples:
            - null
          anyOf:
            - $ref: '#/components/schemas/ServerMaintenanceData'
            - type: 'null'
        maintenance_events:
          type: array
          description: >-
            Every maintenance or incident that affects this server, most
            pressing first. `maintenance` is the first of these.
          examples:
            - []
          items:
            $ref: '#/components/schemas/ServerMaintenanceData'
        location:
          type: string
          description: >-
            The city the server stands in, e.g. "Nuremberg, DE". A location is a
            city now; `displayName()` also reads back the older codes that
            carried the product alongside it in brackets.
          examples:
            - Kansas City, MO
        product_group_name:
          type:
            - string
            - 'null'
          description: >-
            The product the server was sold as, such as `Standard VPS`, or null
            when no product is linked.
          examples:
            - Standard VPS
        user:
          $ref: '#/components/schemas/AccountOwnerData'
          description: >-
            The account the server belongs to, present only when a caller asked
            for it by name.
      required:
        - id
        - uuid
        - hostname
        - name
        - description
        - status
        - suspension_reason
        - power_state
        - windows
        - template_name
        - template_icon_url
        - custom_icon_url
        - default_icon_url
        - created_at
        - usages
        - limits
        - internal_id
        - restoration_progress
        - installation_progress
        - install_failed_at
        - cpu_throttle
        - bandwidth
        - provisioning_scripts_supported
        - snapshots_supported
        - maintenance
        - maintenance_events
        - location
        - product_group_name
      title: ServerData
    ServerUsagesData:
      type: object
      description: >-
        What a server has actually consumed this cycle. Every figure is in
        bytes.
      examples:
        - bandwidth: 500000000000
          actual_bandwidth: 500000000000
          rx: 200000000000
          tx: 300000000000
      properties:
        bandwidth:
          type: integer
          description: >-
            The billed figure, clamped to whatever allowance was in force when
            it was accrued.
          examples:
            - 500000000000
        actual_bandwidth:
          type:
            - integer
            - 'null'
          description: >-
            The unclamped counter, which is what the pool is shared against.
            Null on a server that has never been metered.
          examples:
            - 500000000000
        rx:
          type: integer
          description: >-
            Inbound and outbound halves of the accrued usage, accounted on the
            public NIC only. Servers that last accrued before the split was
            recorded carry zeroes here while `bandwidth` is non-zero, so a
            consumer has to read 0/0 as "not broken down" rather than as "no
            traffic".
          examples:
            - 200000000000
        tx:
          type: integer
          description: The value of `tx`.
          examples:
            - 300000000000
      required:
        - bandwidth
        - actual_bandwidth
        - rx
        - tx
      title: ServerUsagesData
    ServerLimitsData:
      type: object
      description: The resources and transfer allowance included with a server.
      examples:
        - cpu: 4
          memory: 4294967296
          disk: 85899345920
          hdd_disk: null
          snapshots: 2
          backups: 2
          bandwidth: 5497558138880
          addresses:
            ipv4:
              - id: 58213
                address_pool_id: 4
                server_id: 4821
                user_id: null
                type: ipv4
                is_primary: true
                address: 203.0.113.24
                cidr: 24
                gateway: 203.0.113.1
                mac_address: 52:54:00:3a:7c:91
                onlink: null
                floating_ip_uuid: null
              - id: 58391
                address_pool_id: 4
                server_id: 4821
                user_id: null
                type: ipv4
                is_primary: false
                address: 203.0.113.88
                cidr: 24
                gateway: 203.0.113.1
                mac_address: 52:54:00:3a:7c:91
                onlink: null
                floating_ip_uuid: null
            ipv6:
              - id: 58214
                address_pool_id: 5
                server_id: 4821
                user_id: null
                type: ipv6
                is_primary: false
                address: 2001:db8:4b2:18::1
                cidr: 64
                gateway: 2001:db8:4b2::1
                mac_address: 52:54:00:3a:7c:91
                onlink: 2001:db8:4b2::18
                floating_ip_uuid: null
          mac_address: 52:54:00:3a:7c:91
          effective_bandwidth: 5497558138880
          bandwidth_blocks: 0
          plan_bandwidth: 5497558138880
      properties:
        cpu:
          type: integer
          description: The value of `cpu`.
          examples:
            - 4
        memory:
          type: integer
          description: Memory and disk are in bytes; their columns are kept in mebibytes.
          examples:
            - 4294967296
        disk:
          type: integer
          description: The value of `disk`.
          examples:
            - 85899345920
        hdd_disk:
          type:
            - integer
            - 'null'
          description: >-
            Secondary spinning disk, in bytes. Null on a server sold without
            one.
          examples:
            - null
        snapshots:
          type:
            - integer
            - 'null'
          description: The value of `snapshots`.
          examples:
            - 2
        backups:
          type:
            - integer
            - 'null'
          description: The value of `backups`.
          examples:
            - 2
        bandwidth:
          type:
            - integer
            - 'null'
          description: >-
            The PLAN's own allowance, in bytes, not the ceiling in force. Null
            on an unmetered server.
          examples:
            - 5497558138880
        addresses:
          $ref: '#/components/schemas/ServerAddressesData'
          description: The value of `addresses`.
          examples:
            - ipv4:
                - id: 58213
                  address_pool_id: 4
                  server_id: 4821
                  user_id: null
                  type: ipv4
                  is_primary: true
                  address: 203.0.113.24
                  cidr: 24
                  gateway: 203.0.113.1
                  mac_address: 52:54:00:3a:7c:91
                  onlink: null
                  floating_ip_uuid: null
                - id: 58391
                  address_pool_id: 4
                  server_id: 4821
                  user_id: null
                  type: ipv4
                  is_primary: false
                  address: 203.0.113.88
                  cidr: 24
                  gateway: 203.0.113.1
                  mac_address: 52:54:00:3a:7c:91
                  onlink: null
                  floating_ip_uuid: null
              ipv6:
                - id: 58214
                  address_pool_id: 5
                  server_id: 4821
                  user_id: null
                  type: ipv6
                  is_primary: false
                  address: 2001:db8:4b2:18::1
                  cidr: 64
                  gateway: 2001:db8:4b2::1
                  mac_address: 52:54:00:3a:7c:91
                  onlink: 2001:db8:4b2::18
                  floating_ip_uuid: null
        mac_address:
          type:
            - string
            - 'null'
          description: The value of `mac_address`.
          examples:
            - 52:54:00:3a:7c:91
        effective_bandwidth:
          type:
            - integer
            - 'null'
          description: >-
            The transfer ceiling actually enforced: the plan's allowance plus
            whatever the customer has bought, or their share of the city's pool.
            Null when the server is unmetered.
          examples:
            - 5497558138880
        bandwidth_blocks:
          type: integer
          description: >-
            Transfer granted on top of the plan, in bytes. Zero, never negative,
            for a pooled server whose share of the city has been eaten by a
            heavier neighbour.
          examples:
            - 0
        plan_bandwidth:
          type:
            - integer
            - 'null'
          description: >-
            The plan's allowance again, published beside the effective one so
            that neither has to be guessed from the other. A customer holding a
            block is not living on the figure their plan sold them, and the
            meter on the server says so in both numbers.
          examples:
            - 5497558138880
      required:
        - cpu
        - memory
        - disk
        - hdd_disk
        - snapshots
        - backups
        - bandwidth
        - addresses
        - mac_address
        - effective_bandwidth
        - bandwidth_blocks
        - plan_bandwidth
      title: ServerLimitsData
    ServerCpuThrottleData:
      type: object
      description: The CPU cap currently in force on a server, for the banner shown on it.
      examples:
        - cap_percent: 33
          average_cpu: 91.7
          threshold_percent: 80
          window_minutes: 60
          capped_at: '2026-09-14T14:05:00+00:00'
          release_at: '2026-09-14T20:05:00+00:00'
          manual: false
      properties:
        cap_percent:
          type:
            - integer
            - 'null'
          description: The ceiling being enforced, as a percentage of one core.
          examples:
            - 33
        average_cpu:
          type:
            - number
            - 'null'
          description: What the server averaged over the window that earned it the cap.
          examples:
            - 91.7
        threshold_percent:
          type: integer
          description: >-
            The installation's tunables rather than this server's: the figure
            the average was judged against, and the length of the window it was
            measured over. Carried so the banner can say why the cap happened
            without a second request for the settings row.
          examples:
            - 80
        window_minutes:
          type: integer
          description: The value of `window_minutes`.
          examples:
            - 60
        capped_at:
          type:
            - string
            - 'null'
          description: The date and time for capped at, in UTC.
          examples:
            - '2026-09-14T14:05:00+00:00'
        release_at:
          type:
            - string
            - 'null'
          description: When the cap lifts on its own. Null on a cap set by hand.
          examples:
            - '2026-09-14T20:05:00+00:00'
        manual:
          type: boolean
          description: Whether an administrator applied this rather than the sweep.
          examples:
            - false
      required:
        - cap_percent
        - average_cpu
        - threshold_percent
        - window_minutes
        - capped_at
        - release_at
        - manual
      title: ServerCpuThrottleData
    ServerBandwidthData:
      type: object
      description: >-
        The transfer picture drawn by the bandwidth allocator, for the banner
        and the meter on the server.
      examples:
        - limit: 7696581394432
          plan_limit: 5497558138880
          block_bytes: 2199023255552
          shaped: false
          pooled: false
          pool: null
      properties:
        limit:
          type: integer
          description: The ceiling in force, in bytes.
          examples:
            - 7696581394432
        plan_limit:
          type: integer
          description: The plan's own allowance, for the half of the meter it accounts for.
          examples:
            - 5497558138880
        block_bytes:
          type: integer
          description: >-
            Everything this server has been granted beyond its own plan. In a
            pool that is not the same as what its owner bought: a quiet
            neighbour's unused share is lent out too, and the city's own
            purchased balance is reported on `pool` instead.
          examples:
            - 2199023255552
        shaped:
          type: boolean
          description: Whether the server is being rate limited right now.
          examples:
            - false
        pooled:
          type: boolean
          description: The value of `pooled`.
          examples:
            - false
        pool:
          description: Null when the server is not pooled, or its location is unknown.
          examples:
            - null
          anyOf:
            - $ref: '#/components/schemas/ServerBandwidthPoolData'
            - type: 'null'
      required:
        - limit
        - plan_limit
        - block_bytes
        - shaped
        - pooled
        - pool
      title: ServerBandwidthData
    ServerMaintenanceData:
      type: object
      description: Maintenance or an incident that affects a server.
      examples:
        - uuid: e7f8cb40-a971-4c6c-8af8-8f6066bb253e
          type: maintenance
          scope: node
          status: scheduled
          is_live: false
          title: Host kernel update
          body: >-
            The host is moving to a new kernel. Servers on it are moved to
            another host in Kansas City first, with a pause of a few seconds.
          impact: UNDERMAINTENANCE
          impact_label: Under maintenance
          target: null
          starts_at: '2026-09-17T06:00:00+00:00'
          ends_at: '2026-09-17T08:00:00+00:00'
          status_url: https://status.example.com/cmf2x7k0q0001ab12cd34ef56
      properties:
        uuid:
          type: string
          description: The uuid UUID.
          examples:
            - e7f8cb40-a971-4c6c-8af8-8f6066bb253e
        type:
          type: string
          description: A planned window, or unplanned disruption.
          enum:
            - maintenance
            - incident
          examples:
            - maintenance
        scope:
          type: string
          description: >-
            Whether this covers only the host the server runs on (`node`) or a
            whole city (`location`).
          enum:
            - location
            - node
          examples:
            - node
        status:
          type: string
          description: The value of `status`.
          enum:
            - scheduled
            - in_progress
            - identified
            - monitoring
            - completed
            - cancelled
          examples:
            - scheduled
        is_live:
          type: boolean
          description: Whether it is happening now rather than scheduled or finished.
          examples:
            - false
        title:
          type: string
          description: The value of `title`.
          examples:
            - Host kernel update
        body:
          type:
            - string
            - 'null'
          description: The message body.
          examples:
            - >-
              The host is moving to a new kernel. Servers on it are moved to
              another host in Kansas City first, with a pause of a few seconds.
        impact:
          type: string
          description: >-
            How severely the maintenance affects the component, with a readable
            label.
          enum:
            - OPERATIONAL
            - UNDERMAINTENANCE
            - DEGRADEDPERFORMANCE
            - PARTIALOUTAGE
            - MAJOROUTAGE
          examples:
            - UNDERMAINTENANCE
        impact_label:
          type: string
          description: The value of `impact_label`.
          examples:
            - Under maintenance
        target:
          type:
            - string
            - 'null'
          description: >-
            The city the event covers, or null when it covers only the host the
            server runs on.
          examples:
            - null
        starts_at:
          type:
            - string
            - 'null'
          description: The date and time for starts at, in UTC.
          examples:
            - '2026-09-17T06:00:00+00:00'
        ends_at:
          type:
            - string
            - 'null'
          description: The date and time for ends at, in UTC.
          examples:
            - '2026-09-17T08:00:00+00:00'
        status_url:
          type:
            - string
            - 'null'
          description: Where the event is published on the public status page, if it is.
          examples:
            - https://status.example.com/cmf2x7k0q0001ab12cd34ef56
      required:
        - uuid
        - type
        - scope
        - status
        - is_live
        - title
        - body
        - impact
        - impact_label
        - target
        - starts_at
        - ends_at
        - status_url
      title: ServerMaintenanceData
    AccountOwnerData:
      type: object
      description: Whose key or script this is, in the two words a listing has room for.
      examples:
        - name: Gordon Freeman
          email: gordon.freeman@blackmesa.example.com
      properties:
        name:
          type: string
          description: The name shown to customers.
          examples:
            - Gordon Freeman
        email:
          type: string
          description: The email address.
          examples:
            - gordon.freeman@blackmesa.example.com
      required:
        - name
        - email
      title: AccountOwnerData
    ServerAddressesData:
      type: object
      description: A server's addresses, split by family.
      examples:
        - ipv4:
            - id: 58213
              address_pool_id: 4
              server_id: 4821
              user_id: null
              type: ipv4
              is_primary: true
              address: 203.0.113.24
              cidr: 24
              gateway: 203.0.113.1
              mac_address: 52:54:00:3a:7c:91
              onlink: null
              floating_ip_uuid: null
            - id: 58391
              address_pool_id: 4
              server_id: 4821
              user_id: null
              type: ipv4
              is_primary: false
              address: 203.0.113.88
              cidr: 24
              gateway: 203.0.113.1
              mac_address: 52:54:00:3a:7c:91
              onlink: null
              floating_ip_uuid: null
          ipv6:
            - id: 58214
              address_pool_id: 5
              server_id: 4821
              user_id: null
              type: ipv6
              is_primary: false
              address: 2001:db8:4b2:18::1
              cidr: 64
              gateway: 2001:db8:4b2::1
              mac_address: 52:54:00:3a:7c:91
              onlink: 2001:db8:4b2::18
              floating_ip_uuid: null
      properties:
        ipv4:
          type: array
          description: The value of `ipv4`.
          examples:
            - - id: 58213
                address_pool_id: 4
                server_id: 4821
                user_id: null
                type: ipv4
                is_primary: true
                address: 203.0.113.24
                cidr: 24
                gateway: 203.0.113.1
                mac_address: 52:54:00:3a:7c:91
                onlink: null
                floating_ip_uuid: null
              - id: 58391
                address_pool_id: 4
                server_id: 4821
                user_id: null
                type: ipv4
                is_primary: false
                address: 203.0.113.88
                cidr: 24
                gateway: 203.0.113.1
                mac_address: 52:54:00:3a:7c:91
                onlink: null
                floating_ip_uuid: null
          items:
            $ref: '#/components/schemas/ServerAddressData'
        ipv6:
          type: array
          description: The value of `ipv6`.
          examples:
            - - id: 58214
                address_pool_id: 5
                server_id: 4821
                user_id: null
                type: ipv6
                is_primary: false
                address: 2001:db8:4b2:18::1
                cidr: 64
                gateway: 2001:db8:4b2::1
                mac_address: 52:54:00:3a:7c:91
                onlink: 2001:db8:4b2::18
                floating_ip_uuid: null
          items:
            $ref: '#/components/schemas/ServerAddressData'
      required:
        - ipv4
        - ipv6
      title: ServerAddressesData
    ServerBandwidthPoolData:
      type: object
      description: The shared transfer budget a pooled server draws on.
      examples:
        - location: Los Angeles, CA
          limit: 10995116277760
          usage: 1340000000000
          block_bytes: 0
          exhausted: false
      properties:
        location:
          type: string
          description: The city display name, such as Nuremberg, DE.
          examples:
            - Los Angeles, CA
        limit:
          type: integer
          description: The sum of the member servers' own plan allowances.
          examples:
            - 10995116277760
        usage:
          type: integer
          description: What the members have accrued between them.
          examples:
            - 1340000000000
        block_bytes:
          type: integer
          description: What the team's blocks add to the pool on top of `limit`.
          examples:
            - 0
        exhausted:
          type: boolean
          description: >-
            The whole city is shaped together the moment its shared budget runs
            out, which is what sharing one costs.
          examples:
            - false
      required:
        - location
        - limit
        - usage
        - block_bytes
        - exhausted
      title: ServerBandwidthPoolData
    ServerAddressData:
      type: object
      description: An IP address attached to a server.
      examples:
        - id: 58213
          address_pool_id: 4
          server_id: 4821
          user_id: null
          type: ipv4
          is_primary: true
          address: 203.0.113.24
          cidr: 24
          gateway: 203.0.113.1
          mac_address: 52:54:00:3a:7c:91
          onlink: null
          floating_ip_uuid: null
      properties:
        id:
          type: integer
          description: The id ID.
          examples:
            - 58213
        address_pool_id:
          type: integer
          description: The address pool id ID.
          examples:
            - 4
        server_id:
          type:
            - integer
            - 'null'
          description: The server id ID.
          examples:
            - 4821
        user_id:
          type:
            - integer
            - 'null'
          description: >-
            The account holding this address out of its own allowance, or null
            when an administrator handed it out. On a customer payload a
            non-null value can only ever be the viewer's own account - an
            address reserved by somebody else cannot be attached to their
            server.
          examples:
            - null
        type:
          type: string
          description: The type of operation or resource.
          enum:
            - ipv4
            - ipv6
          examples:
            - ipv4
        is_primary:
          type: boolean
          description: Whether the resource is primary.
          examples:
            - true
        address:
          type: string
          description: The IP address assigned to the resource.
          examples:
            - 203.0.113.24
        cidr:
          type: integer
          description: The network prefix length.
          examples:
            - 24
        gateway:
          type: string
          description: The gateway address for the network.
          examples:
            - 203.0.113.1
        mac_address:
          type:
            - string
            - 'null'
          description: The value of `mac_address`.
          examples:
            - 52:54:00:3a:7c:91
        onlink:
          type:
            - string
            - 'null'
          description: The value of `onlink`.
          examples:
            - null
        floating_ip_uuid:
          type:
            - string
            - 'null'
          description: The floating address purchase holding this row, when there is one.
          examples:
            - null
      required:
        - id
        - address_pool_id
        - server_id
        - user_id
        - type
        - is_primary
        - address
        - cidr
        - gateway
        - mac_address
        - onlink
        - floating_ip_uuid
      title: ServerAddressData
  securitySchemes:
    http:
      type: http
      description: >-
        Your API key, sent as a bearer token. Create one in the control panel
        under API Keys, give it only the permissions the integration needs, and
        copy it when it is created. It cannot be shown again. Each key is
        restricted to one owned team. The key determines the team for every
        request.
      scheme: bearer

````

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