Use the CockroachDB Cloud API

The Cloud API is a REST interface that allows you programmatic access to manage the lifecycle of clusters within your organization. This document pertains to the latest version of the API’s v1 endpoints, 2024-09-16. For more detailed coverage of API endpoints for this version and prior versions, refer to the . To manage clusters and other resources in CockroachDB Cloud, you can also use the , which implements the API.

If you used the API to manage CockroachDB Serverless clusters that have been migrated to CockroachDB Basic, ensure your code is updated to work with CockroachDB Basic.

The Cloud API is rate-limited to 10 requests per second per user. When a request exceeds this limit, it receives an HTTP response with the Retry-After header and a “rate limit exceeded” message.

Call the API

The API uses bearer token authentication, and each request requires a . The secret key is associated with a service account, and inherits the . To send the secret key when making an API call, add the secret key to the Authorization HTTP header sent with the request.

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}"

Authorization: Bearer {secret_key}

Replace with the secret key string you stored when you .

Set the API version

The Cloud API uses date-based versions of the form YYYY-MM-DD, in ISO 8601 format. It is strongly recommended that you use the Cc-Version HTTP header to specify the version of the Cloud API to use. If you omit the Cc-Version header, the Cloud API defaults to the latest version. If you don’t specify the version your application expects, breakage may occur. While we try to minimize the risk of breaking API changes, passing the version explicitly helps to mitigate against this risk and is strongly recommended. If you set an invalid version, you recieve an HTTP 400 response with the message “invalid Cc-Version.”

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --header "Cc-Version: {version}"

Authorization: Bearer {secret_key}
Cc-Version: {version}

Where is the and is the version of the Cloud API.

Create a cluster

Get started by creating a new CockroachDB Basic, Standard, or Advanced cluster.

Create a Basic cluster

To create a cluster, send a POST request to the /v1/clusters endpoint.

The service account associated with the secret key must have the Cluster Admin or Cluster Creator .

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"{cluster_name}","provider":"{cloud_provider}","plan":"BASIC","spec":{"serverless":{"regions":["{region_name}"]}}}'

{
  "name": "{cluster_name}",
  "provider": "{cloud_provider}",
  "plan": "BASIC",
  "spec": {
    "serverless": {
      "regions": [
        "{region_name}"
      ]
    }
  }
}

Where:

is the name of the cluster. The name must be 6-20 characters in length and can include numbers, lowercase letters, and dashes (but no leading or trailing dashes).
is the name of the cloud provider on which you want your cluster to run: AWS, AZURE, or GCP.
is the name of a CockroachDB Cloud . Region names are set by the cloud provider. For example, us-central1 is a GCP region. Available regions vary based on both the selected plan type ( BASIC, STANDARD, or ADVANCED ) and the cloud provider.
plan is set to BASIC for a Basic cluster.

For example, to create a new Basic cluster named basic-test using GCP as the cloud provider and setting specific usage limits:

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"basic-test","provider":"GCP","plan":"BASIC","spec":{"serverless":{"regions":["us-central1"]}}}'

{
  "name": "basic-test",
  "provider": "GCP",
  "plan": "BASIC",
  "spec": {
    "serverless": {
      "regions": [
        "us-central1"
      ]
    }
  }
}

If the request is successful, the API returns information about the new cluster. For details about returned fields, refer to the in the API reference.

Create a Standard cluster

To create a cluster, send a POST request to the /v1/clusters endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Creator .

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"{cluster_name}","provider":"{cloud_provider}","plan":"STANDARD","spec":{"serverless":{"regions":["{region_name}"],"usage_limits":{"provisioned_virtual_cpus":"2"}}}}'

{
  "name": "{cluster_name}",
  "provider": "{cloud_provider}",
  "plan": "STANDARD",
  "spec": {
    "serverless": {
      "regions": [
        "{region_name}"
      ],
      "usage_limits": {
        "provisioned_virtual_cpus": "2"
      }
    }
  }
}

Where:

is the name of the cluster. The name must be 6-20 characters in length and can include numbers, lowercase letters, and dashes (but no leading or trailing dashes).
is the name of the cloud provider on which you want your cluster to run: AWS, AZURE, or GCP.
is the name of a CockroachDB Cloud . Region names are set by the cloud provider. For example, us-west2 is a GCP region. Available regions vary based on both the selected plan type ( BASIC, STANDARD, or ADVANCED ) and the cloud provider.
plan is the cluster’s plan, BASIC, STANDARD, or ADVANCED. The default is STANDARD.
The usage_limits field specifies the resource limits for the cluster. The provisioned_virtual_cpus field indicates the maximum number of virtual CPUs (vCPUs) the cluster can provision.

For example, to create a new Standard cluster named notorious-moose using the default values for the cloud provider and region:

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"notorious-moose","provider":"GCP","plan":"STANDARD","spec":{"serverless":{"regions":["us-central1"],"usage_limits":{"provisioned_virtual_cpus":"2"}}}}'

{
  "name": "notorious-moose",
  "provider": "GCP",
  "plan": "STANDARD",
  "spec": {
    "serverless": {
      "regions": [
        "us-central1"
      ],
      "usage_limits": {
        "provisioned_virtual_cpus": "2"
      }
    }
  }
}

If the request is successful, the API returns information about the new cluster. For details about returned fields, refer to the in the API reference.

Create an Advanced cluster

To create a cluster, send a POST request to the /v1/clusters endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Creator .

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"{cluster_name}","provider":"{cloud_provider}","plan":"ADVANCED","spec":{"dedicated":{"region_nodes":{"{region_name}":3},"hardware":{"machine_spec":{"num_virtual_cpus":{num_vcpus}}},"cockroach_version":"{version}"}}}'

{
  "name": "{cluster_name}",
  "provider": "{cloud_provider}",
  "plan": "ADVANCED",
  "spec": {
    "dedicated": {
      "region_nodes": {
        "{region_name}": 3
      },
      "hardware": {
        "machine_spec": {
          "num_virtual_cpus": {num_vcpus}
        }
      },
      "cockroach_version": "{version}"
    }
  }
}

Where:

is the name of the cluster. The name must be 6-20 characters in length and can include numbers, lowercase letters, and dashes (but no leading or trailing dashes).
is the name of the cloud provider on which you want your cluster to run: AWS, AZURE, or GCP.
plan is set to ADVANCED for an Advanced cluster.
is the name of a CockroachDB Cloud . Region names are set by the cloud provider. For example, us-east-1 is an AWS region. Available regions vary based on both the selected plan type and the cloud provider.
The region_nodes field specifies the number of nodes in each region. The minimum is 3 nodes per region for an Advanced cluster.
is the number of virtual CPUs per node in the cluster. This value determines the machine type that is provisioned.
is the CockroachDB version for the cluster. This field is optional; if omitted, the current version is used.

For example, to create a new Advanced cluster named advanced-test using AWS as the cloud provider:

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"advanced-test","provider":"AWS","plan":"ADVANCED","spec":{"dedicated":{"region_nodes":{"us-east-1":3},"hardware":{"machine_spec":{"num_virtual_cpus":4}},"cockroach_version":"v23.1.2"}}}'

{
  "name": "advanced-test",
  "provider": "AWS",
  "plan": "ADVANCED",
  "spec": {
    "dedicated": {
      "region_nodes": {
        "us-east-1": 3
      },
      "hardware": {
        "machine_spec": {
          "num_virtual_cpus": 4
        }
      },
      "cockroach_version": "v23.1.2"
    }
  }
}

If the request is successful, the API returns information about the new cluster. For details about returned fields, refer to the in the API reference.

Get information about a specific cluster

To retrieve detailed information about a specific cluster, make a GET request to the /v1/clusters/{cluster_id} endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Developer .

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
  --header "Authorization: Bearer {secret_key}"

Where:

is the cluster ID returned after creating the cluster.

The cluster ID used in the Cloud API is different from the routing ID used when .

is the secret key for the service account.

If the request is successful, the API returns detailed information about the cluster. For details about returned fields, refer to the in the API reference.

Get information about a CockroachDB Advanced cluster’s nodes

To retrieve information about a CockroachDB Advanced cluster’s nodes, including the node status, make a GET request to the /v1/clusters/{cluster_id}/nodes endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Developer .

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/nodes \
  --header "Authorization: Bearer {secret_key}"

Where:

is the cluster ID returned after creating the cluster. The cluster ID used in the Cloud API is different from the routing ID used when .
is the secret key for the service account.

If the request is successful, the API returns detailed information about the nodes in the cluster.

{
  "nodes": [
    {
      "name": "<node_name}",
      "region_name": "{region_name}",
      "status": "{status}"
    }
  ],
  "pagination": {
    "next": 0,
    "last": 0,
    "limit": 0,
    "total_results": 0,
    "time": "2022-03-14T14:15:22Z",
    "order": "ASC"
  }
}

Where:

is the name of the node.
is the cloud provider region where the cluster is located.
is the status of the node: LIVE or NOT_READY.

Set or update resource limits for a Basic cluster

To specify the maximum RU or storage limits for a cluster, send a PATCH request to the /v1/clusters/{cluster_id} endpoint with an updated serverless.usage_limits field.

The spend_limit field, which was deprecated in Serverless, is not supported on Basic or Standard. Instead, use usage_limits.

The service account associated with the secret key must have the Cluster Admin or Cluster Developer . To export audit logs for activities and events related to your Cloud organization, send a GET request to the /v1/auditlogevents endpoint.

The service account associated with the secret key must have the Cluster Admin .

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/auditlogevents?starting_from={timestamp}&sort_order={sort_order}&limit={limit} \
  --header "Authorization: Bearer {secret_key}" \
  --header "Cc-Version: {api_version}"

Where:

is an RFC3339 timestamp that indicates the first log entry to fetch. If unspecified, defaults to the time when the Cloud organization was created if is ASC, or the current time if is DESC.
is either ASC (the default) or DESC.
indicates roughly how many entries to return. If any entries would be returned for a timestamp, all entries for that timestamp are always returned. Defaults to 200.
is the Cloud API version.

A request that includes no parameters exports roughly 200 entries in ascending order, starting from when your CockroachDB Cloud organization was created. If the request is successful, the client receives a JSON array consisting of a list of log entries and, depending on the circumstances, a next_starting_from field.

If is ASC, next_starting_from is always returned.
If is DESC, then next_starting_from is returned as long as earlier audit logs are available. It is not returned when the earliest log entry is reached (when the CockroachDB Cloud organization was created).

{
  "entries": [
    "{entry_array}"
  ],
  "next_starting_from": "{timestamp}"
}

Where:

is a structured JSON array of audit log entries.
indicates the timestamp to send to export the next batch of results.

Get invoices for an organization

To list all to an organization, send a GET request to the /v1/invoices endpoint.

The service account associated with the secret key must have the Billing Coordinator or Cluster Admin .

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/invoices \
  --header "Authorization: Bearer {secret_key}"

If the request is successful, the client receives a list of invoices billed to the organization. Each invoice object includes the start and end of the corresponding billing period, with each past invoice showing a status of FINALIZED. An invoice object is also returned for the current billing period showing usage so far with a status of DRAFT.

{
  "invoices": [
    {<current_invoice_object},
    {<past_invoice_object1},
    {<past_invoice_object2}
  ],
  "pagination": null
}

You can request a specific invoice by providing the invoice ID in a GET request to the /v1/invoices/{invoice_id} endpoint:

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/invoices/{invoice_id} \
  --header "Authorization: Bearer {secret_key}"

{
  "invoices": [
    {<invoice_object}
  ],
  "pagination": null
}

List all clusters in an organization

To list all active clusters within an organization, send a GET request to the /v1/clusters endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Developer .

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header "Authorization: Bearer {secret_key}"

To return both active clusters and clusters that have been deleted or failed to initialize, send the show_inactive=true query parameter.

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters?show_inactive=true \
  --header "Authorization: Bearer {secret_key}"

Where:

is the secret key for the service account.

If the request is successful, the client receives a list of all clusters within the organization, in the following format.

{
  "clusters": [
    {<cluster_object1},
    {<cluster_object2},
    {<cluster_object3}
  ],
  "pagination": null
}

List the available regions for a cloud provider

To list the for creating new clusters, send a GET request to the /v1/clusters/available-regions?provider={cloud_provider} endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Developer .

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/available-regions?provider={cloud_provider} \
  --header "Authorization: Bearer {secret_key}"

Where:

is the name of the cloud provider: AWS, AZURE, or GCP.
is the secret key for the service account.

If the request is successful, the client receives a list of available regions for the specified cloud provider.

{
  "regions": [
    "<region_array"
  ]
}

Where:

<region_array is a string array of regions available from the cloud provider.

List the SQL users in a cluster

To list the SQL users in a cluster, send a GET request to the /v1/clusters/{cluster_id}/sql-users endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Developer .

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users \
  --header "Authorization: Bearer {secret_key}"

Where:

is the unique ID of this cluster. The cluster ID used in the Cloud API is different from the routing ID used when .
is the secret key for the service account.

If the request is successful, the client receives a list of SQL users.

{
  "users": [
    {
      "name": "<SQL-username>"
    },
    {
      "name": "<SQL-username>"
    }
  ],
  "pagination": {
    "next_page": "<next_page_token"
  }
}

Where:

<SQL-username> is the SQL username of the user.
<next_page_token is the token to use for retrieving the next page of results, if any.

Create a SQL user

To create a SQL user, send a POST request to the /v1/clusters/{cluster_id}/sql-users endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Creator .

By default, a new SQL user created using the UI or Cloud API is granted the SQL admin role. An admin SQL user has full privileges for all databases and tables in the cluster, and can create additional SQL users and manage their privileges. When possible, it is best practice to to the minimum necessary for their tasks, in keeping with the Principle of Least Privilege (PoLP).

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"{sql_username}","password":"{password}"}'

Where:

is the unique ID of this cluster. The cluster ID used in the Cloud API is different from the routing ID used when .
is the secret key for the service account.
is the username of the new SQL user you want to create.
is the new user’s password.

If the request is successful, the client receives a response with the name of the new user.

{
  "name": "<sql_username"
}

Where <sql_username is the username of the newly created SQL user.

Ensure that you store the password securely, as it cannot be retrieved later. If the password is lost, you’ll need to reset it.

Delete a SQL user

To delete a SQL user, send a DELETE request to the /v1/clusters/{cluster_id}/sql-users/{sql_username} endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Creator .

curl --request DELETE \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username} \
  --header "Authorization: Bearer {secret_key}"

Where:

is the unique ID of this cluster. The cluster ID used in the Cloud API is different from the routing ID used when .
is the username of the SQL user you want to delete.
is the secret key for the service account.

If the request is successful, the client receives a response with the name of the deleted user.

{
  "name": "<sql_username"
}

Deleting a SQL user cannot be undone.

Change a SQL user’s password

To change a SQL user’s password send a PUT request to the /v1/clusters/{cluster_id}/sql-users/{sql_username}/password endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Creator .

curl --request PUT \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username}/password \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"password":"{new_password}"}'

Where:

is the unique ID of this cluster. The cluster ID used in the Cloud API is different from the routing ID used when .
is the username of the SQL user whose password you want to change.
is the new password for the SQL user.

If the request is successful, the client receives a response with the name of the SQL user whose password was changed.

{
  "name": "<sql_username"
}

Where <sql_username is the name of the SQL user whose password was changed.

Configure a CockroachDB Advanced cluster’s maintenance window

To configure a on a CockroachDB Advanced cluster, send a PUT request to the /v1/clusters/{cluster_id}/maintenance-window endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Operator .

curl --request PUT \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
  --header "Authorization: Bearer REPLACE_BEARER_TOKEN" \
  --json '{"offset_duration":"{offset_duration}","window_duration":"{window_duration}"}'

Where:

is the unique ID of this cluster. The cluster ID used in the Cloud API is different from the routing ID used when .
is the start of the maintenance window, calculated as the amount of time after the start of a week (Monday 00:00 UTC) to begin the window.
is the length of the maintenance window, which must be greater than 6 hours and less than one week.

To view a cluster’s existing maintenance window, send a GET request to the /api/v1/clusters/{cluster_id}/maintenance-window endpoint:

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
  --header "Authorization: Bearer REPLACE_BEARER_TOKEN"

{
  "offset_duration": "172800s",
  "window_duration": "21600s"
}

To remove a cluster’s maintenance window, send a DELETE request to the /api/v1/clusters/{cluster_id}/maintenance-window endpoint:

curl --request DELETE \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
  --header "Authorization: Bearer REPLACE_BEARER_TOKEN"

{
  "offset_duration": "172800s",
  "window_duration": "21600s"
}

Set a patch upgrade deferral policy

Automatic patch upgrades can be delayed for a period of 30, 60, or 90 days to ensure that development and testing clusters are upgraded before production clusters. This setting applies only to patch upgrades and not to major version upgrades. To set a patch upgrade deferral policy, send a PUT request to the /api/v1/clusters/{cluster_id}/version-deferral endpoint. The service account associated with the secret key must have the Cluster Admin or Cluster Operator .

curl --request PUT \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \
  --header "Authorization: Bearer REPLACE_BEARER_TOKEN" \
  --json '{"deferral_policy":"{deferral_policy}"}'

Where:

is the unique ID of this cluster. The cluster ID used in the Cloud API is different from the routing ID used when .
{deferral_policy} is the length of the deferral window, set to “DEFERRAL_30_DAYS” , “DEFERRAL_60_DAYS” , or “DEFERRAL_90_DAYS” . Set to “NOT_DEFERRED”` to remove the deferral policy and apply automatic patch upgrades immediately.

To view the existing patch deferral policy and current patch upgrade deferrals, send a GET request to the /api/v1/clusters/{cluster_id}/version-deferral endpoint.

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \
  --header "Authorization: Bearer REPLACE_BEARER_TOKEN"

{
  "deferral_policy": "DEFERRAL_60_DAYS",
  "deferred_until": "2025-12-15T00:00:00Z"
}

​Call the API

​Set the API version

​Create a cluster

​Create a Basic cluster

​Create a Standard cluster

​Create an Advanced cluster

​Get information about a specific cluster

​Get information about a CockroachDB Advanced cluster’s nodes

​Set or update resource limits for a Basic cluster

​Get invoices for an organization

​List all clusters in an organization

​List the available regions for a cloud provider

​List the SQL users in a cluster

​Create a SQL user

​Delete a SQL user

​Change a SQL user’s password

​Configure a CockroachDB Advanced cluster’s maintenance window

​Set a patch upgrade deferral policy

Call the API

Set the API version

Create a cluster

Create a Basic cluster

Create a Standard cluster

Create an Advanced cluster

Get information about a specific cluster

Get information about a CockroachDB Advanced cluster’s nodes

Set or update resource limits for a Basic cluster

Get invoices for an organization

List all clusters in an organization

List the available regions for a cloud provider

List the SQL users in a cluster

Create a SQL user

Delete a SQL user

Change a SQL user’s password

Configure a CockroachDB Advanced cluster’s maintenance window

Set a patch upgrade deferral policy