v1
Double column
API
CLI
JS Client

Cloud Providers /

List clusters

Lists clusters for the authenticated user or team.

Required permission

Account > Cloud > Clusters > Read

Query parameters

    • per_page

      integer
      The number of results to display per request. Maximum of 100 results per page.
    • page

      integer
      The page number to access.
    • cursor

      string
      The cursor returned from the previous page of results, used to request the next page.

Response body

  • {object}
    Response object.
    • data

      {object} required
      Result data.
      • clusters

        [array] required
        An array of clusters.
        • {object}
          A cluster object.
          • name

            string required
            The name of the cluster.
            min length
            3
            max length
            20
            pattern
            ^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
          • description

            string
            The description of the cluster.
            max length
            200
            pattern
            ^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
          • provider

            string required
            Cloud provider to be used for the selected resource
            one of
            aws, azure, civo, gcp, oci, cloudflare, byok
          • region

            string required
            Region of the cluster.
          • status

            {object}
            • state

              {object}
              • state

                string required
                Current state of the cluster.
              • transitionTime

                string
                Time of the last state transition.
              • reason

                string
                The reason, given the cluster is in an error state.
          • kubernetesVersion

            string
            Deprecated: This field is no longer used, the version is now set by the platform.
          • integrationId

            string
            Existing integration to use for this cluster.
            pattern
            ^((org|team)\/)?[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
          • storage

            {object}
            • storageEnabled

              boolean
            • snapshotsEnabled

              boolean
            • storageClasses

              [array]
              • {object}
                • id

                  string required
                • name

                  string required
                • description

                  string
                • platformMapping

                  string required
                  one of
                  ssd, hdd
                • kubernetesName

                  string required
                • defaultSnapshotClass

                  string
            • snapshotClasses

              [array]
              • {object}
                • id

                  string required
                • name

                  string required
                • description

                  string
                • kubernetesName

                  string required
          • nodePools

            (multiple options: oneOf) required
            An array of node pools for BYOC or BYOK.
            • [array]
              An array of node pools for BYOC.
              • {object}
                Node pool configuration for BYOC clusters
                • id

                  string required
                  ID of existing node pool. Must be passed when modifying existing node pools. Not relevant for new node pools
                  min length
                  3
                  max length
                  63
                  pattern
                  (^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$)|(^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89ABab][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
                • nodeType

                  string required
                  Machine type to be used by the node pool.
                • oci

                  {object}
                  OCI instance specific settings. Must respect ratios as determined by the selected node type.
                  • ocpu

                    integer required
                    min
                    1
                  • memory

                    integer required
                    min
                    1
                • gcp

                  {object}
                  GCP specific settings.
                  • enablePrivateNodes

                    boolean
                    Set this flag to disable public IP assignment for nodes in this node pool.
                • azure

                  {object}
                  Azure specific settings.
                  • systemPool

                    boolean
                    When 'provider' is 'azure', at least one system node pool is required per cluster.
                  • enablePublicNodeIp

                    boolean
                    When 'provider' is 'azure', set this flag to use public node IPs.
                  • vnetSubnetId

                    string
                    ID of the vnet subnet to use.
                • aws

                  {object}
                  AWS specific node pool settings.
                  • launchTemplate

                    {object}
                    Specify a launch template to use for this node pool. When using a launch template, the disk size selection on the node pool level will be ignored.
                    • id

                      string required
                      ID of the launch template to use.
                    • version

                      integer required
                      Version of the launch template that should be used.
                      min
                      1
                • nodeCount

                  integer required
                  Number of nodes to the node pool should be provisioned with.
                  min
                  0
                  max
                  250
                • autoscaling

                  {object}
                  Auto scaling settings to use for the node pool. Requires that the cloud provider supports this feature.
                  • enabled

                    boolean
                  • min

                    integer
                    min
                    0
                    max
                    249
                  • max

                    integer
                    min
                    1
                    max
                    250
                • computeResources

                  {object}
                  • gpu

                    {object}
                    • type

                      string required
                      GPU type associated with the node pool.
                      pattern
                      [a-z0-9]
                    • resources

                      {object} required
                      • memoryInfo

                        {object}
                        • sizeInGiB

                          number
                          Memory amount of the GPU in Gib.
                          min
                          1
                    • count

                      integer required
                      Number of GPUs per node.
                      min
                      1
                    • timeslicing

                      {object}
                      Time-slicing configuration object.
                      • enabled

                        boolean
                        Whether or not to enable time-slicing on the GPU.
                      • numSlices

                        number
                        Sets the amount of slices per GPU, e.g. how many pods may be scheduled concurrently on each GPU.
                        min
                        1
                • preemptible

                  boolean
                  Configures node pool with preemptible / spot instances if enabled.
                • diskType

                  string
                  The disk type to use.
                • diskSize

                  integer required
                  Disk size in GB
                  min
                  1
                • availabilityZones

                  [array] required
                  Zones in which the node pool should be provisioned.
                  • string
                • subnets

                  [array]
                  Subnets ids in which the node pool should be provisioned.
                  • string
                    Subnets id.
                • scheduling

                  {object}
                  Define basic workload scheduling restrictions for this node pool
                  • allowJobs

                    boolean
                    Allow jobs to schedule to this node pool
                  • onlyGpuJobs

                    boolean
                    Restrict job scheduling to jobs which have GPU resources configured. Only relevant for GPU node pools.
                  • allowServices

                    boolean
                    Allow services to schedule to this node pool
                  • onlyGpuServices

                    boolean
                    Restrict service scheduling to services which have GPU resources configured. Only relevant for GPU node pools.
                  • allowAddons

                    boolean
                    Allow addons to schedule to this node pool
                  • allowBuilds

                    boolean
                    Allow builds to schedule to this node pool
                  • onlyGpuBuilds

                    boolean
                    Restrict build scheduling to builds which have GPU resources configured. Only relevant for GPU node pools.
                  • allowCeph

                    boolean
                    Allow the placement of Ceph pods
                • labels

                  {object}
                  Set of label keys and values that can be used for advanced scheduling in combination with resource tag scheduling rules.

                OR

              • [array]
                An array of node pools for BYOK.
                • {object}
                  Node pool configuration for BYOK clusters
                  • id

                    string required
                    ID of the node pool. Must be passed when modifying existing node pools. Not relevant for new node pools
                    min length
                    3
                    max length
                    63
                    pattern
                    (^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$)|(^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89ABab][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
                  • providerId

                    string required
                    ID which identifies kubernetes nodes as belonging to this pool.
                    min length
                    3
                    max length
                    63
                    pattern
                    (^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$)|(^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89ABab][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
                  • computeResources

                    {object}
                    • gpu

                      {object}
                      • supported

                        boolean
                        Whether this node pool consists of GPU nodes .
                      • type

                        string
                        GPU type associated with the node pool.
                        pattern
                        [a-z0-9]
                      • resources

                        {object}
                        • memoryInfo

                          {object}
                          • sizeInGiB

                            number
                            Memory amount of the GPU in Gib.
                            min
                            1
                      • mig

                        {object}
                        Multi-Instance GPU (MIG). configuration object.
                        • enabled

                          boolean
                          Whether or not to enable Multi-Instance GPU (MIG).
                        • partitions

                          [array]
                          The partitions to configure on the GPU.
                          • string
                      • timeslicing

                        {object}
                        Time-slicing configuration object.
                        • enabled

                          boolean
                          Whether or not to enable time-slicing on the GPU.
                        • numSlices

                          number
                          Sets the amount of slices per GPU, e.g. how many pods may be scheduled concurrently on each GPU.
                          min
                          1
                      • count

                        integer
                        Number of GPUs per node.
                        min
                        1
                  • defaultPool

                    boolean
                    Fallback pool to which nodes which do not match any defined node pool are assigned. Exactly one default pool is required.
                  • preemptible

                    boolean
                    Configures node pool with preemptible / spot instances if enabled.
                  • scheduling

                    {object}
                    Define basic workload scheduling restrictions for this node pool
                    • allowJobs

                      boolean
                      Allow jobs to schedule to this node pool
                    • onlyGpuJobs

                      boolean
                      Restrict job scheduling to jobs which have GPU resources configured. Only relevant for GPU node pools.
                    • allowServices

                      boolean
                      Allow services to schedule to this node pool
                    • onlyGpuServices

                      boolean
                      Restrict service scheduling to services which have GPU resources configured. Only relevant for GPU node pools.
                    • allowAddons

                      boolean
                      Allow addons to schedule to this node pool
                    • allowBuilds

                      boolean
                      Allow builds to schedule to this node pool
                    • onlyGpuBuilds

                      boolean
                      Restrict build scheduling to builds which have GPU resources configured. Only relevant for GPU node pools.
                    • allowCeph

                      boolean
                      Allow the placement of Ceph pods
                  • labels

                    {object}
                    Set of label keys and values that can be used for advanced scheduling in combination with resource tag scheduling rules.
              • settings

                {object}
                • builds

                  {object}
                  • mode

                    string
                    one of
                    paas, internal, build-cluster
                  • plan

                    string
                    Plan to use for builds if they are run on the cluster
                    min length
                    3
                    max length
                    39
                    pattern
                    ^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
                  • clusterId

                    string
                    Cluster to use for scheduling builds
                    pattern
                    ^((org|team)\/)?[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
                • registry

                  {object}
                  • mode

                    string
                    one of
                    paas, self-hosted
                  • registryId

                    string
                    Credentials to use for storing of images.
                    pattern
                    ^((org|team)\/)?[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
                • logging

                  (multiple options: oneOf)
                  Logging settings
                  • {object}
                    Logging via PaaS.
                    • mode

                      string
                      one of
                      paas

                    OR

                  • {object}
                    Logging via Loki (S3 storage).
                    • mode

                      string required
                      one of
                      loki
                    • loki

                      {object}
                      • storageType

                        string required
                        one of
                        s3
                      • s3Region

                        string required
                      • s3BucketName

                        string required

                    OR

                  • {object}
                    Logging via Loki (GCS storage).
                    • mode

                      string required
                      one of
                      loki
                    • loki

                      {object}
                      • storageType

                        string required
                        one of
                        gcs
                      • gcsBucketName

                        string required
                      • gcpIntegrationId

                        string required
                        pattern
                        ^((org|team)\/)?[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
                • vanityDomains

                  {object}
                  • apps

                    {object}
                    • zoneName

                      string required
                    • integrationId

                      string required
                  • customDomains

                    {object}
                    • zoneName

                      string required
                    • integrationId

                      string required
                  • loadBalancers

                    {object}
                    • zoneName

                      string required
                    • integrationId

                      string required
                • infrastructure

                  {object}
                  • workloads

                    {object}
                    • runtimeClass

                      string
                      one of
                      none, gvisor, kata-clh, kata-qemu, katars-clh
                  • builds

                    {object}
                    • runtimeClass

                      string
                      one of
                      none, gvisor, kata-clh, kata-qemu, katars-clh
                  • installKata

                    boolean
                  • installGvisor

                    boolean
                  • cleanupVolumes

                    boolean
                  • cleanupSnapshots

                    boolean
                  • cephStorageProvider

                    {object}
                    • enabled

                      boolean
                    • resources

                      {object}
                      • cpu

                        number
                        Configure the CPU resources per Ceph replica
                        min
                        1
                        max
                        20
                      • memory

                        number
                        Configure the memory resources per Ceph replica
                        min
                        4096
                        max
                        40960
                      • storage

                        number
                        Configure the data disk size per Ceph replica
                        min
                        102400
                        max
                        5242880
                    • enableMultiReadWriteStorage

                      boolean
                      Configure Ceph to be enable use of multi read write storage for persistent volumes on the cluster.
                    • enableSingleReadWriteStorage

                      boolean
                      Configure Ceph to be used as default storage class for single read write storage. This will replace the default storage of the cloud provider.
                    • enableErasureCoding

                      boolean
                      Configure Ceph to be set up with erasure coding. This will be less fault tolerant but more cost effective.
                • requestModifiers

                  {object}
                  Allows customising request modifier values.
                  • services

                    {object}
                    Request modifiers for services
                    • cpu

                      number required
                      min
                      0.2
                      max
                      1
                    • memory

                      number required
                      min
                      0.4
                      max
                      1
                  • jobs

                    {object}
                    Request modifiers for jobs
                    • cpu

                      number required
                      min
                      0.2
                      max
                      1
                    • memory

                      number required
                      min
                      0.4
                      max
                      1
                  • builds

                    {object}
                    Request modifiers for builds
                    • cpu

                      number required
                      min
                      0.1
                      max
                      1
                    • memory

                      number required
                      min
                      0.1
                      max
                      1
                  • addons

                    {object}
                    Request modifiers for addons
                    • cpu

                      number required
                      min
                      0.2
                      max
                      1
                    • memory

                      number required
                      min
                      0.4
                      max
                      1
                • skipInstall

                  boolean
              • restrictions

                {object}
                BYOC restrictions configuration for controlling team access
                • enabled

                  boolean required
                  Enable or disable BYOC restrictions for this entity
                • teams

                  [array]
                  List of teams that have access to this BYOC cluster
                  • {object}
                    • teamId

                      string required
                      The ID of the team that has access to this BYOC cluster
              • gcp

                {object}
                GCP specific data. Required when `provider` is `gcp`
                • networking

                  {object}
                  • network

                    string
                  • subnetwork

                    string
                • enableAuthorizedIpRanges

                  boolean
                • authorizedIpRanges

                  [array]
                  • string
                    pattern
                    ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/([0-9]|[1-2][0-9]|3[0-2]))$
                • projectId

                  string
                  GCP Project ID
                  pattern
                  ^[a-z][a-z0-9-]{4,28}[a-z0-9]$
              • aws

                {object}
                AWS specific data. Required when `provider` is `aws`.
                • enablePublicAccessCidrs

                  boolean
                • publicAccessCidrs

                  [array]
                  • string
                    pattern
                    ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/([0-9]|[1-2][0-9]|3[0-2]))$
                • subnetConfiguration

                  {object}
                  • mode

                    string required
                    The mode of the AWS subnet configuration
                    one of
                    default-subnets-for-azs, explicit-subnets
                  • vpcId

                    string
                    Id of the VPC
                  • subnets

                    [array] required
                    List of subnets the cluster should be created for. At least 2 must be specified.
                    • string
                • vpcEgress

                  boolean
                  If egress traffic from the cluster should come from a single static egress IP.
              • oci

                {object}
                OCI specific data. Required when `provider` is `oci`.
                • vcnConfiguration

                  {object} required
                  • vcnId

                    string required
                  • subnetIdForKubernetesApi

                    string required
                  • subnetIdsForServiceLBs

                    [array] required
                    • string
              • azure

                {object}
                Azure specific data. Required when `provider` is `azure`.
                • networking

                  {object}
                  • vnetConfiguration

                    {object}
                    • mode

                      string required
                      The vnet mode to use for this cluster. Use this to switch between creation of a new vnet per cluster or specifying a custom vnet.
                      one of
                      create-default, custom-vnet
                    • vnetId

                      string
                      Azure vnetId that should be used for this cluster. By default a new vnet will be created.
                  • networkPluginMode

                    string
                    Optional setting to configure overlay mode on Azure.
                    one of
                    overlay
                • enableAuthorizedIpRanges

                  boolean
                • authorizedIpRanges

                  [array]
                  • string
                    pattern
                    ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/([0-9]|[1-2][0-9]|3[0-2]))$
              • byok

                {object}
                BYOK specific data. Required when `provider` is `byok`.
                • nodePoolProviderIdLabel

                  string required
              • id

                string required
                Identifier for the cluster.
        • pagination

          {object} required
          Data about the endpoint pagination.
          • hasNextPage

            boolean required
            Is there another page of results available?
          • cursor

            string
            The cursor to access the next page of results.
          • count

            number required
            The number of results returned by this request.
      API
      CLI
      JS Client

      GET /v1/cloud-providers/clusters

      Example response

      200 OK

      A list of clusters for the authenticated user

      JSON

      {
        "data": {
          "clusters": [
            {
              "name": "GCP Cluster 1",
              "description": "This is a new cluster.",
              "provider": "gcp",
              "region": "europe-west2",
              "status": {
                "state": {
                  "state": "running"
                }
              },
              "kubernetesVersion": "1.30",
              "integrationId": "gcp-integration",
              "nodePools": [
                {
                  "id": "6aa96121-0345-43ad-bade-af36d540c222",
                  "nodeType": "n2-standard-8",
                  "nodeCount": 3,
                  "autoscaling": {
                    "enabled": true,
                    "min": 0,
                    "max": 10
                  },
                  "computeResources": {
                    "gpu": {
                      "type": "h100",
                      "resources": {
                        "memoryInfo": {
                          "sizeInGiB": 80
                        }
                      },
                      "count": 1
                    }
                  },
                  "preemptible": false,
                  "diskSize": 100
                }
              ],
              "settings": {
                "builds": {
                  "plan": "nf-compute-200"
                },
                "registry": {
                  "registryId": "my-registry-credentials"
                },
                "requestModifiers": {
                  "services": {
                    "cpu": 0.5,
                    "memory": 0.8
                  },
                  "jobs": {
                    "cpu": 0.5,
                    "memory": 0.8
                  },
                  "builds": {
                    "cpu": 0.2,
                    "memory": 0.5
                  },
                  "addons": {
                    "cpu": 0.5,
                    "memory": 0.8
                  }
                }
              },
              "aws": {
                "subnetConfiguration": {
                  "subnets": [
                    "eu-west-1a"
                  ]
                }
              },
              "id": "gcp-cluster-1"
            }
          ]
        },
        "pagination": {
          "hasNextPage": false,
          "count": 1
        }
      }

      © 2025 Northflank Ltd. All rights reserved.