> ## Documentation Index > Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get extended information about a cluster > Can be used by the following roles assigned at the organization, folder or cluster scope: - ORG_ADMIN - CLUSTER_ADMIN - CLUSTER_OPERATOR_WRITER - CLUSTER_DEVELOPER - FOLDER_ADMIN - FOLDER_MOVER - METRICS_VIEWER - CLUSTER_MONITOR ## OpenAPI ````yaml /openapi/cloud/latest.json get /api/v1/clusters/{cluster_id} openapi: 3.0.0 info: contact: email: support@cockroachlabs.com name: Cockroach Labs Support url: https://support.cockroachlabs.com description: An API for managing CockroachDB Cloud resources title: CockroachDB Cloud API version: '2024-09-16' servers: - url: https://cockroachlabs.cloud security: - Bearer: [] tags: - name: SCIM - name: Organizations - name: Clusters - name: Cluster Disruption - name: SQL Users - name: SQL Privilege Grants - name: Databases - name: Customer-managed Encryption Keys - name: Client CA Certificates - name: Cluster SSO - name: Log Export - name: Metric Export - name: Audit Logs - name: IP Allowlists - name: Egress Rules - name: Billing - name: Maintenance Windows - name: Blackout Windows - name: Role Management - name: Service Accounts - name: API Keys - name: Folders - name: Version Deferral - name: JWT Issuers - name: OpenID Connect Configuration - name: Private Endpoint Services - name: PCI - name: Physical Cluster Replication - name: Plan Migrations - name: Backup/Restore - name: Egress Private Endpoints - name: Multifactor Authentication externalDocs: description: Use the CockroachDB Cloud API url: https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api.html paths: /api/v1/clusters/{cluster_id}: get: tags: - Clusters summary: Get extended information about a cluster description: > Can be used by the following roles assigned at the organization, folder or cluster scope: - ORG_ADMIN - CLUSTER_ADMIN - CLUSTER_OPERATOR_WRITER - CLUSTER_DEVELOPER - FOLDER_ADMIN - FOLDER_MOVER - METRICS_VIEWER - CLUSTER_MONITOR operationId: CockroachCloud_GetCluster parameters: - name: cluster_id in: path required: true schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/Cluster' '400': description: Returned when a request field is invalid. content: application/json: schema: {} '401': description: Returned when the token bearer cannot be authenticated. content: application/json: schema: {} '403': description: >- Returned when the user does not have permission to access the resource. content: application/json: schema: {} '404': description: Returned when the resource does not exist. content: application/json: schema: {} '500': description: Server error content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: curl source: |- curl --request GET \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' components: schemas: Cluster: type: object properties: account_id: description: >- account_id is a cloud provider account ID representing the CockroachDB cluster. This ID can be used for setting up trust relationships with cloud resources. For GCP clusters, this value is a project name that can be used to construct principal service account names for authentication. type: string azure_cluster_identity_client_id: description: >- The client ID of the Azure cluster identity associated with this cluster. This field is only populated for clusters deployed on Azure and is used to support customer-managed encryption keys (CMEK). type: string cidr_range: description: >- cidr_range is the IPv4 range in CIDR format that will be used by the cluster. It is only set on GCP Advanced tier clusters and is otherwise empty. type: string cloud_provider: $ref: '#/components/schemas/CloudProvider.Type' cockroach_version: type: string config: $ref: '#/components/schemas/ClusterConfig' created_at: type: string format: date-time creator_id: type: string customer_cloud_account: $ref: '#/components/schemas/CustomerCloudAccount' delete_protection: $ref: '#/components/schemas/DeleteProtectionState.Type' deleted_at: type: string format: date-time egress_traffic_policy: $ref: '#/components/schemas/EgressTrafficPolicy.Type' id: type: string labels: description: >- labels are key-value pairs used to organize and categorize resources. type: object additionalProperties: type: string name: type: string network_visibility: $ref: '#/components/schemas/NetworkVisibility.Type' operation_status: $ref: '#/components/schemas/ClusterStatus.Type' parent_id: description: |- Preview: The parent ID is a folder ID. A "root" valued parent ID refers to a cluster at the root level. type: string plan: $ref: '#/components/schemas/Plan.Type' regions: type: array items: $ref: '#/components/schemas/Region' sql_dns: description: sql_dns is the DNS name of SQL interface of the cluster. type: string state: $ref: '#/components/schemas/ClusterState.Type' updated_at: type: string format: date-time upgrade_status: $ref: '#/components/schemas/ClusterUpgradeStatus.Type' example: account_id: '' cidr_range: 172.28.0.0/14 cloud_provider: GCP cockroach_version: v21.2.4 config: serverless: routing_id: example-cluster-1533 upgrade_type: AUTOMATIC usage_limits: provisioned_virtual_cpus: '2' created_at: '2022-03-22T20:23:11.285067Z' creator_id: 7cde0cd9-0d8a-4008-8f90-45092ce8afc1 id: 35c4abb2-bb66-46d7-afed-25ebef5ed2aa is_customer_cloud_account: false labels: cost_center: '12345' env: prod name: example-cluster operation_status: UNSPECIFIED plan: STANDARD regions: - internal_dns: internal-free-tier7.gcp-us-central1.crdb.io name: us-central1 node_count: 0 private_endpoint_dns: private-free-tier7.gcp-us-central1.crdb.io sql_dns: free-tier7.gcp-us-central1.crdb.io ui_dns: '' state: CREATED updated_at: '2022-03-22T20:23:11.879593Z' upgrade_status: UPGRADE_AVAILABLE required: - id - name - cockroach_version - upgrade_status - plan - cloud_provider - state - creator_id - operation_status - config - regions - cidr_range - labels - is_customer_cloud_account Status: type: object properties: code: format: int32 type: integer details: type: array items: $ref: '#/components/schemas/Any' message: type: string CloudProvider.Type: description: |2- - GCP: The Google Cloud Platform cloud provider. - AWS: The Amazon Web Services cloud provider. - AZURE: The Azure cloud provider. type: string enum: - GCP - AWS - AZURE ClusterConfig: type: object properties: dedicated: $ref: '#/components/schemas/DedicatedHardwareConfig' serverless: $ref: '#/components/schemas/ServerlessClusterConfig' CustomerCloudAccount: type: object properties: aws: $ref: '#/components/schemas/AwsCustomerCloudAccount' azure: $ref: '#/components/schemas/AzureCustomerCloudAccount' gcp: $ref: '#/components/schemas/GcpCustomerCloudAccount' DeleteProtectionState.Type: type: string enum: - ENABLED - DISABLED EgressTrafficPolicy.Type: description: >2- - UNSPECIFIED: UNSPECIFIED signifies the egress traffic policy is unspecified. - ERROR: ERROR signifies there has been an internal server error during an update to the egress traffic policy. - ALLOW_ALL: ALLOW_ALL signifies all outbound connections from CockroachDB are allowed. - DEFAULT_DENY: DEFAULT_DENY signifies that CockroachDB can only initiate network connections to destinations explicitly allowed by the user or CockroachDB Cloud operators. - UPDATING: UPDATING signifies the egress traffic policy is updating. type: string enum: - UNSPECIFIED - ERROR - ALLOW_ALL - DEFAULT_DENY - UPDATING NetworkVisibility.Type: type: string enum: - PUBLIC - PRIVATE ClusterStatus.Type: type: string enum: - UNSPECIFIED - CRDB_MAJOR_UPGRADE_RUNNING - CRDB_MAJOR_UPGRADE_FAILED - CRDB_MAJOR_ROLLBACK_RUNNING - CRDB_MAJOR_ROLLBACK_FAILED - CRDB_PATCH_RUNNING - CRDB_PATCH_FAILED - CRDB_SCALE_RUNNING - CRDB_SCALE_FAILED - MAINTENANCE_RUNNING - CRDB_INSTANCE_UPDATE_RUNNING - CRDB_INSTANCE_UPDATE_FAILED - CRDB_EDIT_CLUSTER_RUNNING - CRDB_EDIT_CLUSTER_FAILED - CRDB_CMEK_OPERATION_RUNNING - CRDB_CMEK_OPERATION_FAILED - TENANT_RESTORE_RUNNING - TENANT_RESTORE_FAILED - CRDB_LOG_EXPORT_OPERATION_RUNNING - CRDB_LOG_EXPORT_OPERATION_FAILED - CRDB_CLUSTER_DISRUPTION_RUNNING - CRDB_CLUSTER_DISRUPTION_FAILED - CRDB_REPAVE_RUNNING - CRDB_REPAVE_FAILED - CRDB_CUSTOM_CLIENT_CA_RUNNING - CRDB_CUSTOM_CLIENT_CA_FAILED - DEDICATED_FULL_CLUSTER_RESTORE_RUNNING - DEDICATED_FULL_CLUSTER_RESTORE_FAILED Plan.Type: description: >2- - BASIC: The Basic plan includes essential operational features, is available in select regions, and offers on-demand capacity, making it ideal for small teams with unpredictable workloads. - STANDARD: The Standard plan includes standard enterprise security and monitoring features, is available in all supported regions, and offers provisioned pricing, making it the default choice for most CockroachDB production workloads. - ADVANCED: The Advanced plan is ideal for workloads with stringent isolation, compliance, and security requirements such as CMEK, PCI and HIPAA-readiness, and support for dedicated hardware. Customers are advised to have their account team and/or Cockroach Labs Support involved when provisioning Advanced clusters. type: string enum: - BASIC - STANDARD - ADVANCED Region: type: object properties: disk_iops: description: >- disk_iops is the provisioned disk I/O operations per second for nodes in this region. Only meaningful for Advanced clusters on AWS; for GCP and Azure the cloud provider chooses based on disk size. type: integer format: int32 internal_dns: description: >- internal_dns is the internal DNS name of the cluster within the cloud provider's network. It is used to connect to the cluster with AWS PrivateLink, Azure Private Link, and GCP VPC Peering, but not GCP Private Service Connect. type: string machine_type: description: >- machine_type is the machine type identifier within the cloud provider for nodes in this region (e.g. m5.xlarge, n2-standard-4). May differ across regions in a heterogeneous Advanced cluster. Only populated for Advanced clusters. type: string name: type: string node_count: description: node_count will be 0 for Serverless clusters. type: integer format: int32 num_virtual_cpus: description: >- num_virtual_cpus is the number of virtual CPUs per node in this region, derived from machine_type. Only populated for Advanced clusters. type: integer format: int32 primary: description: >- primary is true only for the primary region in a Multi Region Serverless cluster. type: boolean private_endpoint_dns: description: |- private_endpoint_dns is the DNS name of the cluster which is used to connect to the cluster with GCP Private Service Connect. type: string s3_vpc_endpoint_id: description: |- s3_vpc_endpoint_id is the ID of the AWS S3 VPC gateway endpoint associated with this cluster region. This can be used to configure S3 bucket policies that restrict access to traffic from this VPC endpoint. Only populated for Advanced clusters on AWS. type: string sql_dns: description: >- sql_dns is the DNS name of SQL interface of the cluster. It is used to connect to the cluster with IP allowlisting. type: string ui_dns: description: >- ui_dns is the DNS name used when connecting to the DB Console for the cluster. type: string required: - name - sql_dns - ui_dns - node_count - internal_dns - private_endpoint_dns ClusterState.Type: description: >2- - LOCKED: An exclusive operation is being performed on this cluster. Other operations should not proceed if they did not set a cluster into the LOCKED state. type: string enum: - CREATING - CREATED - CREATION_FAILED - DELETED - LOCKED ClusterUpgradeStatus.Type: description: |2- - FINALIZED: The cluster is running the latest available CockroachDB version, and all upgrades have been finalized. - MAJOR_UPGRADE_RUNNING: An major version upgrade is currently in progress. - UPGRADE_AVAILABLE: An upgrade is available. If preview builds are enabled for the parent organization, this could indicate that a preview upgrade is available. - PENDING_FINALIZATION: An upgrade is complete, but pending finalization. Upgrades are automatically finalized after 72 hours. For more information, see https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version.html - ROLLBACK_RUNNING: A rollback operation is currently in progress. type: string enum: - FINALIZED - MAJOR_UPGRADE_RUNNING - UPGRADE_AVAILABLE - PENDING_FINALIZATION - ROLLBACK_RUNNING Any: description: >- `Any` contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. In its binary encoding, an `Any` is an ordinary message; but in other wire forms like JSON, it has a special encoding. The format of the type URL is described on the `type_url` field. Protobuf APIs provide utilities to interact with `Any` values: - A 'pack' operation accepts a message and constructs a generic `Any` wrapper around it. - An 'unpack' operation reads the content of an `Any` message, either into an existing message or a new one. Unpack operations must check the type of the value they unpack against the declared `type_url`. - An 'is' operation decides whether an `Any` contains a message of the given type, i.e. whether it can 'unpack' that type. The JSON format representation of an `Any` follows one of these cases: - For types without special-cased JSON encodings, the JSON format representation of the `Any` is the same as that of the message, with an additional `@type` field which contains the type URL. - For types with special-cased JSON encodings (typically called 'well-known' types, listed in https://protobuf.dev/programming-guides/json/#any), the JSON format representation has a key `@type` which contains the type URL and a key `value` which contains the JSON-serialized value. The text format representation of an `Any` is like a message with one field whose name is the type URL in brackets. For example, an `Any` containing a `foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`. type: object properties: '@type': description: >- Identifies the type of the serialized Protobuf message with a URI reference consisting of a prefix ending in a slash and the fully-qualified type name. Example: type.googleapis.com/google.protobuf.StringValue This string must contain at least one `/` character, and the content after the last `/` must be the fully-qualified name of the type in canonical form, without a leading dot. Do not write a scheme on these URI references so that clients do not attempt to contact them. The prefix is arbitrary and Protobuf implementations are expected to simply strip off everything up to and including the last `/` to identify the type. `type.googleapis.com/` is a common default prefix that some legacy implementations require. This prefix does not indicate the origin of the type, and URIs containing it are not expected to respond to any requests. All type URL strings must be legal URI references with the additional restriction (for the text format) that the content of the reference must consist only of alphanumeric characters, percent-encoded escapes, and characters in the following set (not including the outer backticks): `/-.~_!$&()*+,;=`. Despite our allowing percent encodings, implementations should not unescape them to prevent confusion with existing parsers. For example, `type.googleapis.com%2FFoo` should be rejected. In the original design of `Any`, the possibility of launching a type resolution service at these type URLs was considered but Protobuf never implemented one and considers contacting these URLs to be problematic and a potential security issue. Do not attempt to contact type URLs. type: string additionalProperties: {} DedicatedHardwareConfig: type: object properties: disk_iops: description: |- disk_iops is the number of disk I/O operations per second that are permitted on each node in the cluster. This value reflects the actual provisioned IOPS, which may differ from the value specified during cluster creation or update. Only AWS clusters support user-specified IOPS; for GCP and Azure clusters, IOPS is determined by the cloud provider based on disk size. A value of zero indicates the cloud provider-specific default. type: integer format: int32 machine_type: description: |- machine_type is the machine type identifier within the given cloud provider, ex. m5.xlarge, n2-standard-4. type: string memory_gib: description: memory_gib is the memory GiB per node in the cluster. type: number format: float num_virtual_cpus: description: >- num_virtual_cpus is the number of virtual CPUs per node in the cluster. type: integer format: int32 storage_gib: description: storage_gib is the number of storage GiB per node in the cluster. type: integer format: int32 required: - machine_type - num_virtual_cpus - storage_gib - memory_gib - disk_iops ServerlessClusterConfig: type: object properties: routing_id: description: routing_id is used to identify the cluster in a connection string. type: string upgrade_type: $ref: '#/components/schemas/UpgradeType.Type' usage_limits: $ref: '#/components/schemas/UsageLimits' required: - routing_id - upgrade_type AwsCustomerCloudAccount: type: object properties: arn: description: >- The ARN string of the role that CockroachDB Cloud will assume to perform actions in the customer-owned AWS account. The ARN contains the account ID so CockroachDB Cloud doesn't require it to be passed separately. type: string required: - arn AzureCustomerCloudAccount: type: object properties: subscription_id: description: >- The ID of the subscription in the customer-owned Azure tenant in which clusters will be created. type: string tenant_id: description: >- The ID of the customer-owned tenant in which the subscription exists. type: string required: - subscription_id - tenant_id GcpCustomerCloudAccount: type: object properties: service_account_email: description: |- The customer-owned GCP service account email. This is the principal that will be impersonated by CockroachDB Cloud to perform actions in the customer-owned GCP project. The service account email contains the project ID, so CockroachDB Cloud doesn't require it to be passed separately. type: string required: - service_account_email UpgradeType.Type: type: string enum: - MANUAL - AUTOMATIC UsageLimits: type: object properties: provisioned_virtual_cpus: description: >- provisioned_virtual_cpus is the maximum number of vCPUs that the cluster can use. Once this limit is reached, operation latency may increase due to throttling. It is an error for this to be zero. type: string format: int64 request_unit_limit: description: >- request_unit_limit is the maximum number of request units that the cluster can consume during the month. If this limit is exceeded, then the cluster is disabled until the limit is increased, or until the beginning of the next month when more free request units are granted. It is an error for this to be zero. type: string format: int64 storage_mib_limit: description: >- storage_mib_limit is the maximum number of Mebibytes of storage that the cluster can have at any time during the month. If this limit is exceeded, then the cluster is throttled; only one SQL connection is allowed at a time, with the expectation that it is used to delete data to reduce storage usage. It is an error for this to be zero. type: string format: int64 securitySchemes: Bearer: type: http scheme: bearer ````