---
title: "Copies a folder asynchronously. You can use ListFolder to preview the operation using the `dryRun` parameter."
method: POST
path: "/v2/accounts/{accountId}/folders/copy"
tags: ["Folder"]
---

# Copies a folder asynchronously. You can use ListFolder to preview the operation using the \`dryRun\` parameter.

`POST /v2/accounts/{accountId}/folders/copy`

## Request

- Base URL: `https://api.bytescale.com`
- URL: `https://api.bytescale.com/v2/accounts/{accountId}/folders/copy`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/bytescale/apis/bytescale-api/docs/v2/accounts/:accountId/folders/copy/post.ts> (a function with typed inputs; its response is checked against the schema)

Copies a folder asynchronously.

You can use ListFolder to preview the operation using the `dryRun` parameter.

## Path parameters

- `accountId` string, required: Your account ID. This is visible on the settings page: https://www.bytescale.com/dashboard/settings

## Request body

- CopyFolderRequest: Request body for CopyFolder.
  - `copyFiles` boolean: If `true` then copies files. Default: true
  - `copyOverriddenStorage` boolean: If `false` then if a file's parent folder has overridden storage settings, the file won't be copied. If you don't use folders with custom storage settings (like AWS S3 buckets), you don't need to worry about this setting. Conditional: `copyVirtualFolders` and `copyOverriddenStorage` cannot both be `true`. Default: false
  - `copyVirtualFolders` boolean: If `true` then copies virtual folders at the current path and below (virtual folders are folders created using the PutFolder operation). If `false` then virtual folders will not be copied, meaning no folder settings will be copied to the destination, but the files of any virtual folders will still be copied if `copyFiles` is set to `true`. Conditional: `copyVirtualFolders` and `copyOverriddenStorage` cannot both be `true`. Default: true
  - `destination` string, required: Absolute path to a folder. Begins with a `/`. Should not end with a `/`.
  - `metadata` CopyFileMetadata
    - `merge` boolean: If `true` then merges `value` with the original data, giving precedence to `value`. If `false` then uses `value` as-is, ignoring the original data. Default: false
    - `value` FileMetadata: The file metadata specified in the original upload request as a JSON object.
  - `recursive` boolean: If `true` then copies files and folders that are descendants of the `source` folder. If `false` then only copies files that are direct children of the `source` folder, and does not copy descendant folders (children or otherwise). Default: true
  - `source` string, required: Absolute path to a folder. Begins with a `/`. Should not end with a `/`.
  - `tags` CopyFileTags
    - `merge` boolean: If `true` then merges `value` with the original data, giving precedence to `value`. If `false` then uses `value` as-is, ignoring the original data. Default: false
    - `value` FileTagName[]: The value to set into the field. Default: empty object / empty array

## Response `200`

Success.

- AsyncResponse: Response body from an API endpoint that performs work asynchronously (i.e. does not complete the work immediately).
  - `jobDocs` 'https://www.bytescale.com/docs/job-api/GetJob', required: Link to the documentation that describes how to get a job's status from its job ID.
  - `jobId` string, required: Job ID.
  - `jobType` 'ProcessImageJob' | 'ProcessVideoJob' | 'ProcessAudioJob' | 'AntivirusJob' | 'ResetCacheJob' | 'DeleteFolderBatchJob' | 'DeleteFileBatchJob' | 'CopyFolderBatchJob' | 'CopyFileBatchJob', required: Job type.
  - `jobUrl` string, required: URL for the job's status. You can `GET` this URL to retrieve the job's status. You must authorize your `GET` request with a ```secret_*``` API key when accessing the URL.

## Other responses

- `401`: Unauthenticated.

## Changes

- **2026-09-01** `d63ecdd9ae9c`: 6 warning, 3 info
  - removed the request property `condition`
  - added the new `AntivirusJob` enum value to the `jobType` response property for the response status `200`
  - added the new `ProcessAudioJob` enum value to the `jobType` response property for the response status `200`
  - added the new `ProcessImageJob` enum value to the `jobType` response property for the response status `200`
  - …5 more

[Operation history](https://skmtc.dev/bytescale/apis/bytescale-api/changes/v2/accounts/:accountId/folders/copy/post.md)

---

[API](https://skmtc.dev/bytescale/apis/bytescale-api.md) - [All operations](https://skmtc.dev/bytescale/apis/bytescale-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bytescale/apis/bytescale-api/revisions/d63ecdd9ae9c?raw)