# Cloning You can **clone** (copy) objects from one data container to another after they reach the "closed" state. This includes copying between projects. To clone objects, you need: * VIEW access or higher to the source container * UPLOAD access or higher to the destination container * The source container must not have the RESTRICTED flag set When you clone an object, the system creates an independent copy in the destination container. This copy includes all user-provided metadata and follows the destination container's permissions. The cloned object has no connection to the original. It is a separate, standalone copy. {% hint style="warning" %} Removing the original object doesn't affect the clone, and modifying the clone's metadata doesn't change the original object. {% endhint %} ## API method: `/class-xxxx/clone` ### Specification This method copies one or more objects and folders from a source container to a destination container. You can optionally specify a destination folder within the target container. #### How cloning works Each object is cloned only once, even if it appears multiple times in the input. When you clone a folder, a new folder with the same name is created in the destination, containing copies of all the source folder's contents. The exception is the root folder ("/"): if specified in `folders`, its contents are copied directly into the destination folder without creating a new subfolder. The system automatically follows links in cloned objects and includes any hidden objects they reference. This process continues recursively for any linked hidden objects. For linked hidden objects outside the source container, linked objects are not cloned to preserve data integrity. For [applets](https://documentation.dnanexus.com/developer/running-analyses/applets-and-entry-points#applets), objects listed in the `bundledDepends` field are automatically included in the clone. Hidden objects within a folder are only cloned if a visible parent object is also being cloned. These hidden objects maintain their relative position within the cloned folder structure, while other hidden objects are placed in the specified destination folder. #### Object type considerations The cloning behavior for workflows depends on the workflow's state. Open workflows create a new replica workflow object in the destination, while closed workflows are cloned directly to the destination. Databases cannot be cloned because they belong to a single project. Database objects must be relocated using move operations instead. If an object already exists in the destination container, it is skipped during cloning. The skipped object IDs are returned in the `exists` array. The clone operation succeeds even if some objects are skipped, but you may need to use the `/move` method to place existing objects in the correct folder. #### Archival object restrictions Objects can only be cloned between projects with the same `billTo` entity when they are in "live", "archival", or "archived" states. Objects transitioning between archival states (from "archival" to "archived" or in "unarchiving" state) cannot be cloned until the transition completes. To clone archival objects between projects with different `billTo` entities, all objects must be in the "live" state. See [archival objects](https://documentation.dnanexus.com/user/objects/archiving-files#file-archival-states) for more details. ### Inputs * `objects` **array of strings** (optional) List of object IDs (strings of the form "class-xxxx") in the source container to be cloned. * Required if `folders` is not provided. * `folders` **array of strings** (optional) List of folders in the source container to be cloned. * Required if `objects` is not provided. * `project` **string** (required) ID of the destination container. * `destination` **string** (optional) The destination folder in `project`. Defaults to `"/"`. * `parents` **boolean** (optional) Whether the destination folder and/or parent folders should be created if they do not exist. Defaults to `false`. ### Outputs * `id` **string** ID of the source container. * `project` **string** ID of the modified destination container. * `exists` **array of strings** List of object IDs that could not be cloned because they already exist in the destination container. ### Errors * InvalidInput * `objects` (if provided) is not an array of nonempty strings * `folders` (if provided) is not an array of nonempty strings * Two of the folders in `folders` have the same name but different paths * `project` is missing or is not a nonempty string unequal to the source container * `destination` (if provided) is not a nonempty string starting with "/" * `parents` if provided is not a boolean * `project` must be in the same region as the source containers of all specified objects. * InvalidType * `project` is not a container ID * ResourceNotFound * The container specified in the URL does not exist * The container specified in `project` does not exist * One or more objects or folder paths in `objects` and `folders` were not found or were not in the source container * The folder specified in `destination` does not exist in the destination container. * PermissionDenied * VIEW access is required in the source container * UPLOAD access is required in the destination container * RESTRICTED flag must not be set in the source container * The source and destination containers must have the same `region`. For more information about regions, see [Regions](https://documentation.dnanexus.com/developer/api/regions). * If the source or destination project is associated with a [TRE](https://documentation.dnanexus.com/developer/api/trusted-research-environments), the source and destination must be associated with the same Data Access Request and satisfy [TRE clone restrictions](https://documentation.dnanexus.com/developer/trusted-research-environments#clone-restrictions). * InvalidState * One or more of the input objects is not in the "closed" state * One or more of the input objects is a database object, or one or more of the input folders contain a database object * There exists a folder in the destination folder `destination` which has the same name as a folder listed in `folders` * The destination project is third-party sponsored and one or more of the input objects is DNAnexus-sponsored * The destination project is third-party sponsored and one or more of the input objects is already third-party sponsored in another project. When this error is thrown, the error `details` is of the form `{alreadySponsored: [{id: ..., project: ...}, ...]}` indicating the ID and sponsoring project of each object that was already third-party sponsored. * Cannot clone one or more objects as they are being archived or unarchived. * Cannot clone one or more objects as they are not in the live state, and the source project and destination project belong to different `billTo` orgs. * Cannot clone one or more objects in folder `folder` as they are being archived or unarchived. * Cannot clone one or more objects in folder `folder` as they are not in the live state, and the source project and destination project belong to different `billTo` orgs. * SpendingLimitExceeded * The `billTo` of the destination project has reached its spending limit and is different from the `billTo` of the source project. * OrgExpired * The `billTo` organization of the destination project has expired. ## API method: `/class-xxxx/listProjects` ### Specification Returns a list of projects that contain the object specified and for which the user has permissions to access. If the token is not full scope, the projects that are returned are filtered to those that the token has at least VIEW access to. ### Inputs * `archivalInfoForOrg` **string** (optional) The org ID of the organization whose org admin is the requesting user. ### Outputs * **key** — the ID of a project that contains the specified object. * **value** **string** — the permission level that the user has in the project. * `liveProjects` **array of strings** IDs of projects that contain a live copy of the file. Those projects are either the ones the requesting user has access to or the ones whose `billTo` is the org specified by `archivalInfoForOrg`. * Only present when `archivalInfoForOrg` is specified. ### Errors * ResourceNotFound * The specified object does not exist * PermissionDenied * Must be the org ADMIN of `archivalInfoForOrg` to return archival info --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.dnanexus.com/developer/api/data-containers/cloning.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.