# Cluster Cloning API

Once you've provisioned a cluster via the Typesense Cloud web console or using the Cluster Management API, you can create a clone of that cluster using the API below.

# Workflow

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

  1. Start a new cloning operation (which is an asynchronous process).
  2. Poll the cloning operation info endpoint to get the status of the cloning operation.
  3. If you need to cancel a pending cloning operation, use the update cloning operation endpoint.

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

# Start a Cloning Operation

This endpoint lets you create a clone of an existing cluster that is in service.

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters/<ClusterId>/cloning-operations" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "typesense_server_version": "28.0",
          "target_region": "oregon",
          "notification_email_addresses": ["email@example.com"]
        }'

Response:

{
  "success": true,
  "cloning_operation": {
    "id": "fbff4b22-23d3-46e8-a599-144b622f4dd4",
    "status": "pending",
    "created_at": 1743046821,
    "updated_at": 1743046821,
    "completed_at": null,
    "source_region": "oregon",
    "target_region": "oregon",
    "typesense_server_version": "28.0",
    "target_cluster_reference_id": null,
    "notification_email_addresses": [
      "email@example.com"
    ]
  }
}

Note

You can only have one cloning operation active / pending at a given time.

# Parameters

You can use any of the following parameters inside the payload of the above API call:

# typesense_server_version

The Typesense Server version for the cloned cluster. If not specified, the source cluster's version will be used.

# target_region

The region where the cloned cluster should be provisioned. This must be one of the valid regions listed here.

# notification_email_addresses

An array of email addresses that will be notified when the cloning operation completes or fails.

# Get single cloning operation

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

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

Response:

{
  "id": "fbff4b22-23d3-46e8-a599-144b622f4dd4",
  "status": "succeeded",
  "created_at": 1742607328,
  "updated_at": 1742608267,
  "completed_at": 1742608267,
  "source_region": "oregon",
  "target_region": "oregon",
  "typesense_server_version": "28.0.rc29",
  "target_cluster_reference_id": "815p962i73hnjcdud",
  "notification_email_addresses": [
    "email@example.com",
    "email@example.net"
  ]
}

# status

The status field can be any of the following values:

status Description
pending Cloning operation is pending execution
in_progress Cloning operation is in progress and cannot be canceled any more
canceled Cloning operation was canceled
succeeded Cloning operation was successfully completed. The completed_at field will give you the time when this cloning operation was completed, and target_cluster_reference_id will contain the ID of the newly created cluster.
failed Cloning operation failed due to an internal error

# List all cloning operations

This endpoint can be used to list all cloning operations for a cluster.

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

Response:

{
  "page": 1,
  "per_page": 1,
  "total": 3,
  "cloning_operations": [
    {
      "id": "fbff4b22-23d3-46e8-a599-144b622f4dd4",
      "status": "succeeded",
      "created_at": 1742607328,
      "updated_at": 1742608267,
      "completed_at": 1742608267,
      "source_region": "oregon",
      "target_region": "oregon",
      "typesense_server_version": "28.0.rc29",
      "target_cluster_reference_id": "815p962i73hnjcdud",
      "notification_email_addresses": [
        "email@example.com",
        "email@example.net"
      ]
    }
  ]
}

# Parameters

You can use the following query parameters with this endpoint:

# per_page

The number of results per page.

Default: 10

# page

Page number to fetch

Default: 1

# Cancel a pending cloning operation

You can use this endpoint to cancel a pending cloning operation.

curl -X PATCH --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>/cloning-operations/<OperationID>" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
      -d '{
        "status": "canceled"
      }'

Response:

{
  "success": true,
  "cloning_operation": {
    "id": "fbff4b22-23d3-46e8-a599-144b622f4dd4",
    "status": "canceled",
    "created_at": 1742607328,
    "updated_at": 1742607328,
    "completed_at": null,
    "source_region": "oregon",
    "target_region": "oregon",
    "typesense_server_version": "28.0.rc29",
    "target_cluster_reference_id": null,
    "notification_email_addresses": [
      "email@example.com",
      "email@example.net"
    ]
  }
}

Note

Only cloning operations in a pending status can be canceled.

This state only exists transiently as the cloning operation is waiting to be picked up by one of the async worker processes.

← Typesense Configuration Parameters →

This documentation site is open source. Found an issue? Edit this page (opens new window) and send us a Pull Request.

For AI Agents: View an easy-to-parse, token-efficient Markdown version of this page. You can also replace .html with .md in any docs URL. For paths ending in /, append README.md to the path.

Last Updated: 3/26/2025, 10:49:30 PM