curl --request POST \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--json '{"cluster_id":"9f8e7d6c-5b4a-3210-fedc-ba9876543210","region":"us-east1"}'{
"bucket_grantee": "arn:aws:iam::123456789012:role/example-role",
"cluster_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
"created_at": "2026-07-30T18:00:00Z",
"deployed_region": "us-east1",
"health": "HEALTHY",
"id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"last_error": "",
"password": "example_password",
"status": "RUNNING",
"updated_at": "2026-07-30T18:05:00Z",
"url": "https://molt-ai.example.crdb.io",
"username": "example_username"
}{
"code": 123,
"details": [
{
"@type": "<string>"
}
],
"message": "<string>"
}Provision a Migration Assistant for a cluster.
The assistant is a per-cluster, dedicated-cluster-only migration tool. Poll GetMigrationAssistant until its status is RUNNING to retrieve the URL and credentials used to sign in, or FAILED to inspect last_error.
Can be used by the following roles assigned at the organization, folder or cluster scope:
- ORG_ADMIN
- CLUSTER_ADMIN
curl --request POST \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--json '{"cluster_id":"9f8e7d6c-5b4a-3210-fedc-ba9876543210","region":"us-east1"}'{
"bucket_grantee": "arn:aws:iam::123456789012:role/example-role",
"cluster_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
"created_at": "2026-07-30T18:00:00Z",
"deployed_region": "us-east1",
"health": "HEALTHY",
"id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"last_error": "",
"password": "example_password",
"status": "RUNNING",
"updated_at": "2026-07-30T18:05:00Z",
"url": "https://molt-ai.example.crdb.io",
"username": "example_username"
}{
"code": 123,
"details": [
{
"@type": "<string>"
}
],
"message": "<string>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The ID of the cluster to deploy the assistant on.
Body
CreateMigrationAssistantRequest provisions a Migration Assistant on a cluster.
The cluster region to deploy into. Optional; empty selects a default region (the cluster's first region ordered by locality, which is not necessarily its original primary region). Must be one of the cluster's existing regions. The chosen region is reported as the assistant's deployed_region.
Response
A successful response.
MigrationAssistant is a per-cluster migration assistant deployment. The url, username, password, and bucket_grantee are populated only while the status is RUNNING. The last_error is populated only when the status is FAILED.
The ID of the cluster this assistant is deployed for.
Timestamp when the assistant was created.
The cluster region the assistant is deployed in.
- NOT_COMPUTED: Health is not computed; the assistant is not RUNNING.
- HEALTHY: The assistant is ready and serving.
- UNAVAILABLE: The assistant is RUNNING but not currently serving. This is usually transient (for example, its pod is restarting); retry shortly.
- UNKNOWN: The live health probe could not be reached, so serving health is not known. This is usually transient; retry shortly.
NOT_COMPUTED, HEALTHY, UNAVAILABLE, UNKNOWN The unique ID of the migration assistant.
- PENDING: The assistant has been requested and is being provisioned.
- RUNNING: The assistant is ready; its URL and credentials are available.
- DELETING: Deletion has been requested and is in progress.
- FAILED: A provisioning or deletion operation failed; see last_error.
PENDING, RUNNING, DELETING, FAILED Timestamp when the assistant was last updated.
The cloud-native identity the customer must grant bucket access to; populated when the status is RUNNING. Format depends on the cluster's cloud (AWS IAM role ARN, GCP service account email, or Azure object ID).
The failure detail; populated when the status is FAILED.
The password used to sign in to the assistant; populated when the status is RUNNING.
The URL used to reach the assistant; populated when the status is RUNNING.
The username used to sign in to the assistant; populated when the status is RUNNING.