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

POST /api/v1/clusters/{cluster_id}/migration-assistant

cURL

cURL

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --json '{"region":"us-east1"}'

200

{
  "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"
}

PREVIEW

This endpoint is in Preview and subject to change. Refer to the API support policy for more details.

Authorizations

Authorization · string · header · required

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

Path Parameters

cluster_id · string · required

The ID of the cluster to deploy the assistant on.

Body

application/json

CreateMigrationAssistantRequest provisions a Migration Assistant on a cluster.

region · string

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

200

application/json

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.

cluster_id · string · required

The ID of the cluster this assistant is deployed for.

created_at · string<date-time> · required

Timestamp when the assistant was created.

deployed_region · string · required

The cluster region the assistant is deployed in.

health · enum<string> · required

• 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.

Available options: NOT_COMPUTED, HEALTHY, UNAVAILABLE, UNKNOWN

id · string · required

The unique ID of the migration assistant.

status · enum<string> · required

• 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.

Available options: PENDING, RUNNING, DELETING, FAILED

updated_at · string<date-time> · required

Timestamp when the assistant was last updated.

bucket_grantee · string

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).

last_error · string

The failure detail; populated when the status is FAILED.

password · string

The password used to sign in to the assistant; populated when the status is RUNNING.

url · string

The URL used to reach the assistant; populated when the status is RUNNING.

username · string

The username used to sign in to the assistant; populated when the status is RUNNING.