Cluster Management API

This section talks about how to use the Typesense Cloud Cluster Management API.

If you're looking for the Typesense Server API docs, see here.

Workflow

Here's a typical sequence of API Calls you'd perform when using this API:

1. Create a new cluster (which is an asynchronous process: a free-tier cluster is usually ready within seconds and other configurations take 4 to 6 minutes).
2. Poll the single cluster info endpoint to get the status of the cluster.
3. Once the cluster has status: in_service, save the hostnames field returned by the cluster info endpoint.
4. Generate Typesense API keys for the cluster and store these keys in a secrets store on your side.
5. Now, you can make Typesense API calls directly to your new cluster using the hostnames in Step 3 and API Keys in Step 4.
6. Once you're done with the cluster, you can terminate it using the lifecycle endpoint.

The rest of this document will talk about the individual endpoints.

Create new cluster

This endpoint lets you provision a new cluster under your Typesense Cloud account.

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "memory": "0.5_gb",
          "vcpu": "2_vcpus_1_hr_burst_per_day",
          "regions": ["oregon"]
        }'

Response:

{
  "success": true,
  "cluster": {
    "id": "az9p28gwxfdsye40d",
    "name": null,
    "memory": "0.5_gb",
    "vcpu": "2_vcpus_1_hr_burst_per_day",
    "gpu": "no",
    "high_performance_disk": "no",
    "typesense_server_version": "0.23.1",
    "high_availability": "no",
    "high_availability_node_count": null,
    "search_delivery_network": "off",
    "load_balancing": "no",
    "regions": [
      "oregon"
    ],
    "region_node_counts": {
      "oregon": 1
    },
    "auto_upgrade_capacity": null,
    "usage": {
      "runtime_hours": 0,
      "used_bandwidth_kb": {
        "last_7_days": {}
      }
    },
    "provisioned_by": {
      "user_name": "API Key: YOUR-API-KEY*****",
      "user_type": "API Key"
    },
    "provisioned_at": 1663382519,
    "status": "provisioning"
  }
}

Request Parameters

You can use any of the following parameters inside the payload of the above API call. The Get cluster options endpoint also returns the values each one accepts, and which regions are available right now.

• memory Required
• vcpu Required
• regions Required
• region_node_counts
• high_availability_node_count
• gpu
• high_availability
• search_delivery_network
• high_performance_disk
• typesense_server_version
• name
• auto_upgrade_capacity

memory

How much RAM this cluster should have. Required

You can use any of the following values:

memory
0.5_gb
1_gb
2_gb
4_gb
8_gb
16_gb
32_gb
64_gb
96_gb
128_gb
192_gb
256_gb
384_gb
512_gb
768_gb
1024_gb

vcpu

How many CPU cores this cluster should have. Required

Only certain CPU configurations are available with particular RAM configurations. The table below lists all available configurations:

memory	vcpu
0.5_gb	2_vcpus_1_hr_burst_per_day
1_gb	2_vcpus_2_hr_burst_per_day
2_gb	2_vcpus_4_hr_burst_per_day
4_gb	2_vcpus_4_hr_burst_per_day 2_vcpus
8_gb	2_vcpus_7_hr_burst_per_day 2_vcpus 4_vcpus
16_gb	2_vcpus 4_vcpus_5_hr_burst_per_day 4_vcpus 8_vcpus
32_gb	4_vcpus 8_vcpus_4_hr_burst_per_day 8_vcpus 16_vcpus
64_gb	4_vcpus 8_vcpus 16_vcpus 32_vcpus
96_gb	12_vcpus 24_vcpus 48_vcpus
128_gb	4_vcpus 8_vcpus 16_vcpus 32_vcpus 64_vcpus
192_gb	24_vcpus 48_vcpus 96_vcpus
256_gb	8_vcpus 16_vcpus 32_vcpus 64_vcpus 128_vcpus
384_gb	48_vcpus 96_vcpus 192_vcpus
512_gb	16_vcpus 32_vcpus 64_vcpus 128_vcpus
768_gb	24_vcpus 48_vcpus 96_vcpus 192_vcpus
1024_gb	32_vcpus 64_vcpus 128_vcpus

You can also get this list from the cluster options endpoint, under vcpu_by_memory.

regions

An array with one or more regions where the nodes should be geographically placed. Required

This field is required unless you provide region_node_counts instead.

• For a non-Search-Delivery-Network cluster, the array should have only one region.
• For a Search Delivery Network (SDN) cluster with the 3_regions or 5_regions option, the array should have 3 or 5 regions respectively, with one node placed in each region.

If you want to place more than one node in a region (for example, a highly available cluster with more than 3 nodes, or a Multi-Nodes Per Region SDN cluster), use region_node_counts instead of regions. You can only specify one of regions or region_node_counts.

The table below lists all available regions:

regions
n_california
oregon
n_virginia
ohio
canada
sao_paulo
ireland
london
paris
zurich
frankfurt
stockholm
milan
spain
cape_town
bahrain
uae
mumbai
hyderabad
singapore
jakarta
seoul
osaka
tokyo
melbourne
sydney

region_node_counts

An object that maps region names to the number of nodes you want placed in each region. Use this instead of regions when you want to control how many nodes go into each region.

For example, to provision a Multi-Nodes Per Region SDN cluster with 2 nodes in Oregon and 1 node in Frankfurt:

{
  "high_availability": "yes",
  "search_delivery_network": "multi_nodes_per_region",
  "region_node_counts": {
    "oregon": 2,
    "frankfurt": 1
  }
}

The region names are the same values listed in the regions table above, and each node count must be a positive integer.

The number of regions and nodes you can specify depends on the cluster's high_availability and search_delivery_network options:

Configuration	Regions	Nodes
Single region, High Availability off	Exactly 1 region	Exactly 1 node
Single region, High Availability on	Exactly 1 region	Between 3 and 7 nodes
search_delivery_network: 3_regions	Exactly 3 regions	1 node per region
search_delivery_network: 5_regions	Exactly 5 regions	1 node per region
search_delivery_network: multi_nodes_per_region	Between 2 and 7 regions	Between 3 and 7 nodes in total

You can only specify one of regions or region_node_counts. To set the number of nodes for a single-region highly available cluster, use high_availability_node_count together with a single regions value instead.

high_availability_node_count

The number of nodes to provision for a single-region highly available cluster. This is a shorthand for specifying region_node_counts with a single region.

This option:

• Can only be used when high_availability is yes.
• Can only be used when search_delivery_network is off.
• Requires exactly one region (specified via regions).
• Must be between 3 and 7.

For example, to provision a 5-node highly available cluster in Oregon:

{
  "high_availability": "yes",
  "regions": ["oregon"],
  "high_availability_node_count": 5
}

You can only specify one of high_availability_node_count or region_node_counts.

gpu

When set to yes, it enables the use of a GPU to accelerate embedding generation when using built-in ML models both during indexing and searching.

This option is only available with the following RAM / CPU configurations:

ram	vcpu
8_gb	4_vcpus
16_gb	4_vcpus
16_gb	8_vcpus
32_gb	8_vcpus
32_gb	16_vcpus
64_gb	16_vcpus
64_gb	32_vcpus
128_gb	32_vcpus
128_gb	64_vcpus
192_gb	48_vcpus
256_gb	64_vcpus
384_gb	96_vcpus

Default: no

high_availability

When set to yes, at least 3 nodes are provisioned in 3 different data centers to form a highly available (HA) cluster and your data is automatically replicated between all nodes.

By default, an HA cluster has 3 nodes. To provision more than 3 nodes (up to 7) in a single region, use high_availability_node_count.

Default: no

search_delivery_network

When not off, nodes are provisioned in different regions and the node that's closest to it's originating location serves the traffic.

Default: off

The table below lists all available options:

search_delivery_network	Description
off	Search Delivery Network is disabled.
3_regions	One node is placed in each of 3 regions.
5_regions	One node is placed in each of 5 regions.
multi_nodes_per_region	Place multiple nodes across 2 to 7 regions, with a custom number of nodes in each region (3 to 7 nodes in total).

When using multi_nodes_per_region, specify the number of nodes for each region using region_node_counts.

IMPORTANT: Make sure you set high_availability to yes when you turn on Search Delivery Network.

high_performance_disk

When set to yes, the provisioned hard disk will be co-located on the same physical server that runs the node.

Default: no

IMPORTANT: This option is only available when:

• The cluster has High Availability turned on
• The cluster does not have a burst CPU type.

typesense_server_version

The Typesense Server version to use for this cluster.

Default: Latest GA release version.

name

A string to identify the cluster for your reference in the Typesense Cloud Web console.

Default: null

auto_upgrade_capacity

When set to true, your cluster will be automatically upgraded when best-practice RAM/CPU thresholds are exceeded in a 12-hour rolling window.

Default: false

Response Parameters

Most response parameters are similar to the request parameters above.

We've documented response-specific parameters below:

regions (response)

In the response, regions is a flat list with one entry per node. For example, a 3-node cluster in Oregon returns ["oregon", "oregon", "oregon"].

During a topology change, this list reflects the nodes that are currently live, which can differ from the target topology reported in region_node_counts.

region_node_counts (response)

An object that maps each region to the number of nodes configured for that region, for example { "oregon": 2, "frankfurt": 1 }. This reflects the cluster's target topology.

high_availability_node_count (response)

The number of nodes for a single-region highly available cluster. This is null when High Availability is off, or when Search Delivery Network is enabled. In those cases, refer to region_node_counts for the number of nodes per region.

cpu_burst

This is only set for clusters on a burst vCPU option (for example 2_vcpus_4_hr_burst_per_day).

cpu_burst	Description
ok	The cluster has burst CPU left
low	The cluster is about to run out of burst CPU
throttled	The cluster has run out of burst CPU, and its CPU is throttled until usage drops
null	Not a burst vCPU option, or too early to tell. The status updates about every 30 minutes

write_backlog

This is null unless the cluster's write queue has grown past what the cluster can keep up with, because of the way data is being written to it. While it's set, writes are rejected with a 503 until the queue drains. We also email the account's cluster alert recipients when this happens.

Here's an example:

"write_backlog": {
  "kind": "single_document_writes",
  "since": 1761600000
}

Field	Description
kind	single_document_writes: a high rate of single-document writes instead of batched imports. import_call_flood: import calls arriving faster than the cluster can index them, with too few documents per call or too many calls in parallel.
since	Unix timestamp, in seconds, of when the condition was first detected.

status

The state of the cluster.

It can have the following values:

status	Description
provisioning	The cluster's nodes are being provisioned
initializing	Typesense cluster is being setup
in_service	Cluster is ready for use
deprovisioning	Cluster is being deprovisioned
suspended	Cluster was suspended due to billing issues
terminated	Cluster was terminated

Get cluster options

This endpoint lists the values you can use when creating a cluster, and which regions are available right now.

curl -X GET --location "https://cloud.typesense.org/api/v1/cluster-options" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Response:

{
  "regions": [
    {"name": "oregon", "available": true},
    {"name": "n_virginia", "available": true},
    {"name": "frankfurt", "available": true},
    {"name": "bahrain", "available": false}
  ],
  "memory": ["0.5_gb", "1_gb", "2_gb", "4_gb", "8_gb", "16_gb", "32_gb", "64_gb", "96_gb", "128_gb", "192_gb", "256_gb", "384_gb", "512_gb", "768_gb", "1024_gb"],
  "vcpu_by_memory": {
    "0.5_gb": ["2_vcpus_1_hr_burst_per_day"],
    "4_gb": ["2_vcpus_4_hr_burst_per_day", "2_vcpus"]
  },
  "gpu": ["yes", "no"],
  "high_performance_disk": ["yes", "no"],
  "high_availability": ["yes", "no"],
  "search_delivery_network": ["off", "3_regions", "5_regions", "multi_nodes_per_region"],
  "free_tier": {
    "memory": "0.5_gb",
    "vcpu": "2_vcpus_1_hr_burst_per_day"
  }
}

The response above is shortened. The actual response lists every region and every memory option.

• regions[].name is the value to use for regions in Create new cluster. A region with "available": false can't be used right now.
• vcpu_by_memory shows which vcpu values go with each memory value. For example, 2_vcpus is available with 4_gb but not with 0.5_gb.
• free_tier is the configuration you can create without adding a payment method.

Check which memory options fit an existing cluster

Before you change an existing cluster's memory with a configuration change, you want to pass its id as cluster_id to this endpoint. The response then also tells you how much memory, CPU and disk the cluster used in the last 7 days and which memory options can hold its data.

curl -X GET --location "https://cloud.typesense.org/api/v1/cluster-options?cluster_id=<ClusterID>" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

The response has the fields above, plus these:

{
  "usage_last_7_days": {
    "peak_memory_used_gb": 3.1,
    "latest_memory_used_gb": 2.8,
    "peak_cpu_percentage": 38.0,
    "vcpus": 4,
    "peak_disk_used_gb": 9.4,
    "window_started_at": "2026-10-06T04:00:00Z"
  },
  "memory_fit": {
    "2_gb": {"fits_current_data": false, "fits_peak_last_7_days": false, "spare_gb": -0.8},
    "4_gb": {"fits_current_data": true, "fits_peak_last_7_days": true, "spare_gb": 1.2},
    "8_gb": {"fits_current_data": true, "fits_peak_last_7_days": true, "spare_gb": 5.2}
  },
  "disk_fit": {
    "2_gb": {"disk_gb": 10, "fits_peak_last_7_days": false},
    "4_gb": {"disk_gb": 20, "fits_peak_last_7_days": true}
  },
  "usage_last_7_days_unavailable_reason": null
}

• usage_last_7_days.peak_memory_used_gb is the peak RAM plus swap used on any node, in GB, rounded up to 0.1.
• usage_last_7_days.latest_memory_used_gb is the RAM plus swap used on any node in the latest complete hour and the current one, in GB, rounded up to 0.1. It's null when those hours have no metrics.
• usage_last_7_days.peak_cpu_percentage is the CPU use in the busiest hour (95th percentile) on any node, as a percentage of the cluster's current vCPUs. It's null until the window has a full hour in it.
• usage_last_7_days.vcpus is the cluster's current number of vCPUs per node.
• usage_last_7_days.peak_disk_used_gb is the peak disk used on any node, in GB, rounded up to 0.1. It's null when the window has no disk metrics.
• usage_last_7_days.window_started_at is where the window starts: 7 days ago, or the first full hour after the cluster's last memory or vCPU change if that's more recent.
• memory_fit has an entry for every memory option:
  • fits_current_data is true when the option is larger than latest_memory_used_gb (or peak_memory_used_gb when that's null). A configuration change to a memory option that doesn't fit is rejected when the change starts.
  • fits_peak_last_7_days is true when the option is larger than peak_memory_used_gb.
  • spare_gb is what would be left over at latest_memory_used_gb, rounded down to 0.1. It's negative when the data doesn't fit.
• disk_fit has an entry for each memory option available with the cluster's current configuration. It's null when the cluster uses high performance disk or when peak_disk_used_gb is null.
  • disk_gb is the disk each node gets with that memory option.
  • fits_peak_last_7_days is true when that disk can hold peak_disk_used_gb without triggering a low disk alert. A configuration change isn't refused because of it.
• usage_last_7_days_unavailable_reason is null, no_metrics (the cluster reported no metrics in the last 7 days) or metrics_unavailable (metrics couldn't be read right now, so you want to retry). When it isn't null, usage_last_7_days, memory_fit and disk_fit are all null.

Generate API key

This endpoint can be used to generate Typesense Server API Keys for your cluster.

You can only generate API keys for a cluster, once its status changes to in_service. A free-tier cluster is usually in_service within seconds. Other configurations take 4 to 6 minutes to go from provisioning to in_service. So you want to poll Get single cluster about every 60 seconds until then.

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>/api-keys" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Response:

{
  "success": true,
  "api_keys": {
    "admin_key": "cBKqFPEcGRAS7RIKi3h3FuJbj4Q9Rprk",
    "search_only_key": "y7CFw2zEgu09FFhoDgLzC99j0RwKi0kL",
    "admin_key_id": 4,
    "search_only_key_id": 5
  }
}

You can use the two ids to revoke these keys later.

This API endpoint is the equivalent of clicking on the "Generate API Keys" button in the Cluster Dashboard on Typesense Cloud Web console.

The Cluster API Keys endpoints also let you list the keys on a cluster or create a key that's limited to certain actions or collections. That page also covers when to use which way of creating keys.

Get single cluster

This endpoint can be used to get information about a single cluster.

curl -X GET --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Response:

{
  "id": "nuj9s7k6vplrg15yp",
  "name": null,
  "memory": "0.5_gb",
  "vcpu": "2_vcpus_1_hr_burst_per_day",
  "gpu": "no",
  "high_performance_disk": "no",
  "typesense_server_version": "0.23.1",
  "high_availability": "yes",
  "high_availability_node_count": 3,
  "search_delivery_network": "off",
  "load_balancing": "yes",
  "regions": [
    "mumbai",
    "mumbai",
    "mumbai"
  ],
  "region_node_counts": {
    "mumbai": 3
  },
  "auto_upgrade_capacity": null,
  "cpu_burst": null,
  "write_backlog": null,
  "hostnames": {
    "load_balanced": "nuj9s7k6vplrg15yp.a1.typesense.net",
    "nodes": [
      "nuj9s7k6vplrg15yp-1.a1.typesense.net",
      "nuj9s7k6vplrg15yp-2.a1.typesense.net",
      "nuj9s7k6vplrg15yp-3.a1.typesense.net"
    ]
  },
  "usage": {
    "runtime_hours": 1,
    "used_bandwidth_kb": {
      "last_7_days": {}
    }
  },
  "provisioned_by": {
    "user_name": "API Key: sc4DyvAzf*****",
    "user_type": "API Key"
  },
  "provisioned_at": 1663616196,
  "status": "in_service"
}

List all clusters

This endpoint can be used to list all clusters under this account. Clusters terminated more than a week ago only show up here while their backups are still kept, and only for a key with backups:read.

curl -X GET --location "https://cloud.typesense.org/api/v1/clusters" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Response:

{
  "page": 1,
  "per_page": 1,
  "total": 2,
  "clusters": [
    {
      "id": "az9p28gwxfdsye40d",
      "name": null,
      "memory": "0.5_gb",
      "vcpu": "2_vcpus_1_hr_burst_per_day",
      "gpu": "no",
      "high_performance_disk": "no",
      "typesense_server_version": "0.23.1",
      "high_availability": "no",
      "high_availability_node_count": null,
      "search_delivery_network": "off",
      "load_balancing": "no",
      "regions": [
        "oregon"
      ],
      "region_node_counts": {
        "oregon": 1
      },
      "auto_upgrade_capacity": false,
      "usage": {
        "runtime_hours": 5643,
        "used_bandwidth_kb": {
          "last_7_days": {}
        }
      },
      "provisioned_by": {
        "user_name": "John Doe",
        "user_type": "User"
      },
      "provisioned_at": 1663382520,
      "status": "initializing"
    }
  ]
}

Request Parameters

Parameter	Required	Description
per_page	Optional	The number of results per page. Default: 10
page	Optional	Page number to fetch. Default: 1

Update cluster attributes

This endpoint can be used to update select cluster attributes.

curl -X PATCH --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "auto_upgrade_capacity": true,
          "name": "New Name"
        }'

Request Parameters

Parameter	Required	Description
auto_upgrade_capacity	Optional	See auto_upgrade_capacity.
name	Optional	See name.

Response:

{
  "success": true,
  "cluster": {
    "id": "az9p28gwxfdsye40d",
    "name": "New Name",
    "memory": "0.5_gb",
    "vcpu": "2_vcpus_1_hr_burst_per_day",
    "gpu": "no",
    "high_performance_disk": "no",
    "typesense_server_version": "0.23.1",
    "high_availability": "no",
    "high_availability_node_count": null,
    "search_delivery_network": "off",
    "load_balancing": "no",
    "regions": ["oregon"],
    "region_node_counts": {
      "oregon": 1
    },
    "auto_upgrade_capacity": true,
    "usage": {
      "runtime_hours": 5643,
      "used_bandwidth_kb": {
        "last_7_days": {}
      }
    },
    "provisioned_by": {
      "user_name": "John Doe",
      "user_type": "User"
    },
    "provisioned_at": 1663382520,
    "status": "in_service"
  }
}

Terminate cluster

This endpoint terminates a running cluster.

WARNING

This action can't be undone. Once a cluster is terminated, all data in it is destroyed permanently as a security and privacy measure.

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>/lifecycle" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "lifecycle_action": "terminate"
        }'

Response:

{
  "success": true,
  "message": "Cluster termination has been initiated"
}

Request Parameters

Parameter	Required	Description
lifecycle_action	Required	Must be terminate.
delete_backups	Optional	When true, the cluster's kept backups are deleted along with it. When false, they're kept until they expire. Default: false

WARNING

You're billed for the storage of kept backups until they expire.

Permissions

To create a cluster, you need a key with the clusters:create capability. To get cluster options, get a cluster or list clusters, you need clusters:read. Checking which memory options fit an existing cluster also needs metrics:read. To generate API keys, you need cluster_credentials:issue. To update cluster attributes, you need clusters:configure. To terminate a cluster, you need clusters:terminate. See capabilities.