The Cluster Management API enables you to create, update, monitor, and delete CockroachDB Cloud clusters across all plan types: Basic, Standard, and Advanced.
List All Clusters Retrieve all active clusters within your organization.
curl --request GET \ --url https://cockroachlabs.cloud/api/v1/clusters \ --header "Authorization: Bearer {secret_key}"
Query Parameters Include deleted or failed clusters in the response
Response Array of cluster objects Unique identifier for the cluster
Cluster name (6-20 characters, lowercase letters, numbers, dashes)
Cluster plan type: BASIC, STANDARD, or ADVANCED
Cloud provider: AWS, GCP, or AZURE
Current cluster state: CREATING, CREATED, DELETED, LOCKED
{ "clusters" : [ { "id" : "f9b6f5e4-3c2b-4a1d-9e8f-7c6b5a4d3e2f" , "name" : "production-cluster" , "plan" : "STANDARD" , "provider" : "GCP" , "state" : "CREATED" , "created_at" : "2024-01-15T10:30:00Z" } ] }
Get Cluster Details Retrieve detailed information about a specific cluster.
GET /v1/clusters/{cluster_id}
curl --request GET \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \ --header "Authorization: Bearer {secret_key}"
The cluster ID used in the Cloud API is different from the routing ID used when connecting to clusters.
Create a Basic Cluster Create a new CockroachDB Basic cluster with usage-based pricing.
curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters \ --header "Authorization: Bearer {secret_key}" \ --header "Content-Type: application/json" \ --data '{ "name": "basic-test", "provider": "GCP", "plan": "BASIC", "spec": { "serverless": { "regions": ["us-central1"] } } }'
Request Parameters Cluster name (6-20 characters, lowercase letters, numbers, dashes)
Cloud provider: AWS, GCP, or AZURE
Set to BASIC for a Basic cluster
Array of region names (e.g., ["us-central1"])
spec.serverless.usage_limits.storage_mib_limit
Maximum storage in MiB (optional)
spec.serverless.usage_limits.request_unit_limit
Maximum request units per month (optional)
Create a Standard Cluster Create a CockroachDB Standard cluster with provisioned capacity.
curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters \ --header "Authorization: Bearer {secret_key}" \ --header "Content-Type: application/json" \ --data '{ "name": "standard-cluster", "provider": "GCP", "plan": "STANDARD", "spec": { "serverless": { "regions": ["us-central1"], "usage_limits": { "provisioned_virtual_cpus": "2" } } } }'
Request Parameters Cloud provider: AWS, GCP, or AZURE
Set to STANDARD for a Standard cluster
spec.serverless.usage_limits.provisioned_virtual_cpus
Number of provisioned vCPUs (minimum 2)
Create an Advanced Cluster Create a CockroachDB Advanced cluster with dedicated resources.
curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters \ --header "Authorization: Bearer {secret_key}" \ --header "Content-Type: application/json" \ --data '{ "name": "advanced-cluster", "provider": "AWS", "plan": "ADVANCED", "spec": { "dedicated": { "region_nodes": { "us-east-1": 3 }, "hardware": { "machine_spec": { "num_virtual_cpus": 4 } } } } }'
Request Parameters Cloud provider: AWS, GCP, or AZURE
Set to ADVANCED for an Advanced cluster
spec.dedicated.region_nodes
Object mapping region names to node counts (minimum 3 nodes per region)
spec.dedicated.hardware.machine_spec.num_virtual_cpus
Number of vCPUs per node
spec.dedicated.cockroach_version
CockroachDB version (e.g., v23.1.2). Defaults to latest if omitted.
Update Cluster Resources Modify cluster resources such as vCPUs, storage limits, or provisioned capacity.
Update Basic Cluster Limits PATCH /v1/clusters/{cluster_id}
curl --request PATCH \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \ --header "Authorization: Bearer {secret_key}" \ --header "Content-Type: application/json" \ --data '{ "serverless": { "usage_limits": { "storage_mib_limit": "5242880", "request_unit_limit": "100000000" } } }'
Update Standard Cluster vCPUs PATCH /v1/clusters/{cluster_id}
curl --request PATCH \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \ --header "Authorization: Bearer {secret_key}" \ --header "Content-Type: application/json" \ --data '{ "serverless": { "usage_limits": { "provisioned_virtual_cpus": "4" } } }'
You can decrease provisioned capacity only three times within a 7-day period. You can increase capacity at any time.
Update Advanced Cluster Hardware PATCH /v1/clusters/{cluster_id}
curl --request PATCH \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \ --header "Authorization: Bearer {secret_key}" \ --header "Content-Type: application/json" \ --data '{ "spec": { "dedicated": { "hardware": { "machine_spec": { "num_virtual_cpus": 8 } } } } }'
Get Cluster Nodes Retrieve information about nodes in a cluster.
GET /v1/clusters/{cluster_id}/nodes
curl --request GET \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/nodes \ --header "Authorization: Bearer {secret_key}"
Response { "nodes" : [ { "name" : "node-1" , "region_name" : "us-central1" , "status" : "LIVE" }, { "name" : "node-2" , "region_name" : "us-central1" , "status" : "LIVE" } ] }
Node status: LIVE or NOT_READY
Delete a Cluster Permanently delete a cluster and all its data.
DELETE /v1/clusters/{cluster_id}
curl --request DELETE \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \ --header "Authorization: Bearer {secret_key}"
Deleting a cluster is permanent and irreversible. All data within the cluster will be lost. Deleted clusters cannot be restored.
List Available Regions Get available regions for creating clusters.
GET /v1/clusters/available-regions
curl --request GET \ --url 'https://cockroachlabs.cloud/api/v1/clusters/available-regions?provider=GCP' \ --header "Authorization: Bearer {secret_key}"
Query Parameters Cloud provider: AWS, GCP, or AZURE
Response { "regions" : [ "us-central1" , "us-east1" , "us-west1" , "europe-west1" , "asia-southeast1" ] }
Required Permissions Operation Required Role List clusters Cluster Developer, Cluster Admin Get cluster details Cluster Developer, Cluster Admin Create cluster Cluster Creator, Cluster Admin Update cluster Cluster Developer, Cluster Admin Delete cluster Cluster Creator, Cluster Admin List available regions Cluster Developer, Cluster Admin