Create a restore

Can be used by the following roles assigned at the organization, folder or cluster scope:

• CLUSTER_ADMIN
• CLUSTER_OPERATOR_WRITER

POST /api/v1/clusters/{destination_cluster_id}/restores

cURL

cURL

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters/{destination_cluster_id}/restores \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --json '{"backup_id":"1234abcd-1234-1234-abcd-12345678abcd","destination_cluster_id":"12345678-1234-1234-1234-123456789012","objects":[{"database":"database1","schema":"schema1","table":"table1"},{"database":"database1","schema":"schema1","table":"table2"}],"restore_opts":{"into_db":"database2","schema_only":true},"type":"TABLE"}'

200

{
  "backup_end_time": "2025-07-09T14:00:00Z",
  "backup_id": "1234abcd-1234-1234-abcd-12345678abcd",
  "completion_percent": 0,
  "created_at": "2025-07-09T15:04:05Z",
  "destination_cluster_name": "dest-cluster",
  "id": "abcd1234-5678-90ab-cdef-1234567890ab",
  "objects": [
    {
      "database": "mydb",
      "schema": "public",
      "table": "users"
    }
  ],
  "source_cluster_name": "src-cluster",
  "status": "PENDING",
  "type": "TABLE"
}

{
  "code": 123,
  "details": [
    {
      "@type": "<string>"
    }
  ],
  "message": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

destination_cluster_id · string · required

The ID of the cluster where the backup will be restored.

Body

application/json

type · enum<string> · required

Available options: CLUSTER, DATABASE, TABLE

backup_id · string

The ID of the backup from which data will be restored. If backup_id is not set, the restore will use the latest available backup from source_cluster_id.

objects · object[]

The list of objects to restore. Required when type is DATABASE or TABLE.

Show child attributes

restore_opts · object

Show child attributes

source_cluster_id · string

The ID of the cluster containing the backup to be restored.

Response

200

application/json

A successful response.

backup_end_time · string<date-time> · required

The timestamp at which the backup data was captured.

backup_id · string · required

The ID of the backup used for this restore job.

completion_percent · number<float> · required

The percentage of the restore job that has been completed. The value ranges from 0 to 1.

created_at · string<date-time> · required

The time at which the restore job was initiated.

destination_cluster_name · string · required

The name of the cluster to which the restore is being applied.

id · string · required

The unique identifier associated with the restore.

source_cluster_name · string · required

The name of the cluster from which the backup was taken.

status · enum<string> · required

Available options: PENDING, SUCCESS, FAILED

type · enum<string> · required

Available options: CLUSTER, DATABASE, TABLE

client_error_code · integer<int32>

Error code from the restore job, only populated if it has failed.

client_error_message · string

Error message from the restore job, only populated if it has failed.

completed_at · string<date-time>

The timestamp at which the restore job completed.

crdb_job_id · string

The CockroachDB internal job ID for the restore job.

objects · object[]

The list of database objects (databases, tables) that were restored.

Show child attributes

restore_opts · object

Show child attributes