Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Ytsaurus API, gRPC: ClusterService.List

Written by
Updated at October 30, 2025

Retrieves the list of clusters in the specified folder.

gRPC request

rpc List (ListClustersRequest) returns (ListClustersResponse)

ListClustersRequest

{
  "folder_id": "string",
  "page_size": "int64",
  "page_token": "string",
  "filter": [
    "string"
  ]
}

Field

Description

folder_id

string

Required field. ID of the folder to list clusters in.

page_size

int64

The maximum number of results per page to return. If the number of available
results is larger than page_size, the service returns a ListClustersResponse.next_page_token
that can be used to get the next page of results in subsequent list requests.
Default value: 100.

page_token

string

Page token. To get the next page of results, set page_token to the
ListClustersResponse.next_page_token returned by a previous list request.

filter[]

string

A filter expression that filters clusters listed in the response.

ListClustersResponse

{
  "clusters": [
    {
      "id": "string",
      "folder_id": "string",
      "zone_id": "string",
      "name": "string",
      "description": "string",
      "labels": "map<string, string>",
      "subnet_id": "string",
      "security_group_ids": [
        "string"
      ],
      "spec": {
        "storage": {
          "hdd": {
            "size_gb": "int64",
            "count": "int64"
          },
          "ssd": {
            "size_gb": "int64",
            "type": "string",
            "count": "int64"
          }
        },
        "compute": [
          {
            "preset": "string",
            "disks": [
              {
                "type": "string",
                "size_gb": "int64",
                "locations": [
                  "string"
                ]
              }
            ],
            "scale_policy": {
              // Includes only one of the fields `fixed`, `auto`
              "fixed": {
                "size": "int64"
              },
              "auto": {
                "min_size": "int64",
                "max_size": "int64"
              }
              // end of the list of possible fields
            },
            "name": "string"
          }
        ],
        "tablet": {
          "preset": "string",
          "count": "int64"
        },
        "proxy": {
          "http": {
            "count": "int64"
          },
          "rpc": {
            "count": "int64"
          }
        },
        "odin": {
          "checks_ttl": "google.protobuf.Duration"
        },
        "flavor": "Flavor"
      },
      "created_at": "google.protobuf.Timestamp",
      "created_by": "string",
      "updated_at": "google.protobuf.Timestamp",
      "updated_by": "string",
      "status": "Status",
      "health": "Health",
      "endpoints": {
        "ui": "string",
        "external_http_proxy_balancer": "string",
        "internal_http_proxy_alias": "string",
        "internal_rpc_proxy_alias": "string"
      }
    }
  ],
  "next_page_token": "string"
}

Field

Description

clusters[]

Cluster

List of clusters in the specified folder.

next_page_token

string

This token allows you to get the next page of results for list requests. If the number of results
is larger than ListClustersRequest.page_size, use the next_page_token as the value
for the ListClustersRequest.page_token query parameter in the next list request.
Each subsequent list request will have its own next_page_token to continue paging through the results.

Cluster

Field

Description

id

string

ID of the cluster. Generated at creation time.

folder_id

string

ID of the folder that the cluster belongs to.

zone_id

string

ID of the availability zone where the cluster resides.

name

string

Name of the cluster.
The name is unique within the folder.

description

string

Description of the cluster.

labels

object (map<string, string>)

Cluster labels as key:value pairs.

subnet_id

string

ID of the subnet where the cluster resides.

security_group_ids[]

string

Network interfaces security groups.

spec

ClusterSpec

Cluster specification.

created_at

google.protobuf.Timestamp

Time when the cluster was created.

created_by

string

User who created the cluster.

updated_at

google.protobuf.Timestamp

Time when the cluster was last updated.

updated_by

string

User who last updated the cluster.

status

enum Status

Status of the cluster.

  • STATUS_UNKNOWN
  • CREATING: Cluster is being created.
  • RUNNING: Cluster is running.
  • ERROR: Cluster encountered a problem and cannot operate.
  • STOPPING: Cluster is being stopped.
  • STOPPED: Cluster stopped.
  • STARTING: Cluster is being started.
  • UPDATING: Cluster is being updated.
  • DELETING: Cluster is being deleted.

health

enum Health

Health of the cluster.

  • HEALTH_UNKNOWN
  • ALIVE: Cluster is alive.
  • DEAD: Cluster is dead.
  • DEGRADED: Cluster is degraded.

endpoints

Endpoints

Endpoints of the cluster.

ClusterSpec

Field

Description

storage

StorageSpec

compute[]

ComputeSpec

tablet

TabletSpec

proxy

ProxySpec

odin

OdinSpec

flavor

enum Flavor

  • FLAVOR_UNSPECIFIED
  • DEMO: Demo cluster configuration with minimal system resources. Not fault-tolerant, not for production use.

StorageSpec

Field

Description

hdd

HddSpec

ssd

SsdSpec

HddSpec

Field

Description

size_gb

int64

count

int64

SsdSpec

Field

Description

size_gb

int64

type

string

count

int64

ComputeSpec

Field

Description

preset

string

disks[]

DiskSpec

scale_policy

ScalePolicy

name

string

Name for exec pool.

DiskSpec

Field

Description

type

string

size_gb

int64

locations[]

string

ScalePolicy

Field

Description

fixed

FixedScale

Includes only one of the fields fixed, auto.

auto

AutoScale

Includes only one of the fields fixed, auto.

FixedScale

Field

Description

size

int64

AutoScale

Field

Description

min_size

int64

max_size

int64

TabletSpec

Field

Description

preset

string

count

int64

ProxySpec

Field

Description

http

HttpProxySpec

rpc

RpcProxySpec

HttpProxySpec

Field

Description

count

int64

RpcProxySpec

Field

Description

count

int64

OdinSpec

Field

Description

checks_ttl

google.protobuf.Duration

Endpoints

Field

Description

ui

string

https://CID.ui.ytsaurus.yandexcloud.net

external_http_proxy_balancer

string

https://CID.proxy.ytsaurus.yandexcloud.net

internal_http_proxy_alias

string

https://hp.CID.ytsaurus.mdb.yandexcloud.net:PORT

internal_rpc_proxy_alias

string

rp.CID.ytsaurus.mdb.yandexcloud.net:PORT
Previous
Get
Next
Create