Copy API reference
The Copy API, or Cloud Clone, lets you copy existing datasets.
The Copy API, also known as Cloud Clone, lets you make a copy of an existing dataset. It offers an alternative to exporting and importing a dataset.
Authentication
All requests must be authenticated. The token needs the create grant on the sanity.project.datasets permission.
Base API server URL
Parameterized base URL
https://api.sanity.io/{apiVersion}Variables
- apiVersionstringdefault:
"v2025-02-19"API version
Endpoints
Copy
/projects/{projectId}/datasets/{dataset}/copyThe Copy API, also known as Cloud Clone, lets you make a copy of an existing dataset. It offers an alternative to exporting and importing a dataset. This feature is also available in the CLI. All requests to this endpoint must be authenticated.
Check the status of the copy operation
You can check the status of the copy operation by making a request to the Jobs API with the returned jobId.
Content releases in the copy
Unless you set skipContentReleases, content releases and their document versions are copied to the target dataset. Scheduled releases are unscheduled in the copy: they arrive with the active state and without a publishAt time.
Paid feature
This feature is part of our Advanced Dataset Management offering on the enterprise plan. Contact us if you need this feature and want to discuss this plan.
Request body application/json
The name of the new dataset. Must adhere to the dataset naming requirements.
Example:production-copyIf true, it skips document history while copying the dataset. This can reduce copy time on datasets with a large edit history. Check the retention period to find out how long a dataset's history is kept.
If true, content releases aren't copied. This skips both the release documents and the document versions that belong to them. Copied releases count against your organization's release quota.
Responses
Returns details about the new copy job. Use the jobId with the Jobs API to check the status.
- datasetNamestring
The name of the source dataset.
Example:production - messagestring
A message indicating the status of the copy operation.
Example:Starting copying dataset production to production-copy... - aclModestring
The ACL mode of the source dataset.
Example:public - jobIdstring
The ID of the job that is running the copy operation.
Example:jacsfsmnxp
The request is invalid, or the project's plan doesn't include the Advanced Dataset Management feature.
- The request body fails validation:
targetDatasetis missing or doesn't match the dataset naming requirements, or the body contains a field this endpoint doesn't accept. The response includes avalidationobject describing the failure. - The plan doesn't include the feature. The error message is "Your current plan does not include the advanced dataset management feature".
- statusCodeinteger
The HTTP status code.
Example:404 - errorstring
The HTTP status text.
Example:Not Found - messagestring
A description of the error.
Example:Source dataset not found - codestring
A machine-readable error code. Present on some errors, such as
missing_granton 401 responses. - validationobject
Details about which part of the request failed validation. Present on 400 validation errors.
The request has no valid token, or the token lacks the create grant on sanity.project.datasets. A missing grant returns 401, not 403, with code set to missing_grant.
- statusCodeinteger
The HTTP status code.
Example:404 - errorstring
The HTTP status text.
Example:Not Found - messagestring
A description of the error.
Example:Source dataset not found - codestring
A machine-readable error code. Present on some errors, such as
missing_granton 401 responses. - validationobject
Details about which part of the request failed validation. Present on 400 validation errors.
The project has reached its dataset quota. The error message is "Quota exceeded" or "Overage quota exceeded". The quota is checked before the source dataset, so a project at its quota gets this error even if the source dataset doesn't exist.
- statusCodeinteger
The HTTP status code.
Example:404 - errorstring
The HTTP status text.
Example:Not Found - messagestring
A description of the error.
Example:Source dataset not found - codestring
A machine-readable error code. Present on some errors, such as
missing_granton 401 responses. - validationobject
Details about which part of the request failed validation. Present on 400 validation errors.
The project or the source dataset doesn't exist. The error message is "Project not found" or "Source dataset not found".
- statusCodeinteger
The HTTP status code.
Example:404 - errorstring
The HTTP status text.
Example:Not Found - messagestring
A description of the error.
Example:Source dataset not found - codestring
A machine-readable error code. Present on some errors, such as
missing_granton 401 responses. - validationobject
Details about which part of the request failed validation. Present on 400 validation errors.
A copy job from this source dataset to targetDataset is already running, or a dataset named targetDataset already exists. The error message is "Job already in progress. Job ID:
- statusCodeinteger
The HTTP status code.
Example:404 - errorstring
The HTTP status text.
Example:Not Found - messagestring
A description of the error.
Example:Source dataset not found - codestring
A machine-readable error code. Present on some errors, such as
missing_granton 401 responses. - validationobject
Details about which part of the request failed validation. Present on 400 validation errors.
The copy job couldn't be started. The error message is "Could not initiate the dataset copying".
- statusCodeinteger
The HTTP status code.
Example:404 - errorstring
The HTTP status text.
Example:Not Found - messagestring
A description of the error.
Example:Source dataset not found - codestring
A machine-readable error code. Present on some errors, such as
missing_granton 401 responses. - validationobject
Details about which part of the request failed validation. Present on 400 validation errors.
List copy jobs
/projects/{projectId}/datasets/copyLists the dataset copy jobs for a project, newest first. The CLI uses this endpoint for sanity dataset copy --list.
The token needs the read grant on the sanity.project.datasets permission. Listing jobs doesn't require the Advanced Dataset Management feature.
To follow a single job, use the Jobs API with its id.
Path parameters
Query parameters
The maximum number of jobs to return. Use a value of 255 or less: larger values wrap around, so
300returns at most 44 jobs and256returns every job.The number of jobs to skip, for paging through results. Use a value of 255 or less: larger values wrap around, so
256starts from the first job again.- statestring
A comma-separated list of job states to filter by. Valid states are
pending,running,completed,failed,terminating, andterminated.Example:pending,running
Responses
Returns an array of copy jobs, newest first.
- idstring
The job ID. Use it with the Jobs API to check the job's status.
Example:jacsfsmnxp - statestring
The current state of the job.
Example:completed - authorsarray
The IDs of the users who started the job. Jobs started by Sanity's own services list
service.Show child attributes
items
- string
- createdAtstring (date-time)Example:
2026-10-20T12:00:00.000Z - updatedAtstring (date-time)Example:
2026-10-20T12:20:00.000Z - sourceDatasetstring
The name of the dataset being copied.
Example:production - targetDatasetstring
The name of the new dataset.
Example:production-copy - withHistoryboolean
Whether the copy includes document history. This is
falsewhen the job was started withskipHistory: true.Example:true
items
A query parameter is invalid: limit is outside 1–1000, offset is negative, or the request includes a query parameter this endpoint doesn't accept. The response includes a validation object describing the failure.
- statusCodeinteger
The HTTP status code.
Example:404 - errorstring
The HTTP status text.
Example:Not Found - messagestring
A description of the error.
Example:Source dataset not found - codestring
A machine-readable error code. Present on some errors, such as
missing_granton 401 responses. - validationobject
Details about which part of the request failed validation. Present on 400 validation errors.
The request has no valid token, or the token lacks the read grant on sanity.project.datasets. A missing grant returns 401, not 403, with code set to missing_grant.
- statusCodeinteger
The HTTP status code.
Example:404 - errorstring
The HTTP status text.
Example:Not Found - messagestring
A description of the error.
Example:Source dataset not found - codestring
A machine-readable error code. Present on some errors, such as
missing_granton 401 responses. - validationobject
Details about which part of the request failed validation. Present on 400 validation errors.
The project doesn't exist, or the job list couldn't be fetched. The error message is "Project not found" or "Could not get a list of the dataset copy jobs". An unrecognized state value also returns the second message.
- statusCodeinteger
The HTTP status code.
Example:404 - errorstring
The HTTP status text.
Example:Not Found - messagestring
A description of the error.
Example:Source dataset not found - codestring
A machine-readable error code. Present on some errors, such as
missing_granton 401 responses. - validationobject
Details about which part of the request failed validation. Present on 400 validation errors.