---
title: "Start extracting a backup's files to a folder"
method: POST
path: "/WebsiteBackup/extract_backup"
tags: ["WebsiteBackup"]
---

# Start extracting a backup's files to a folder

`POST /WebsiteBackup/extract_backup`

## Request

- Base URL: `https://cpanel-server.tld:2083/execute`
- URL: `https://cpanel-server.tld:2083/execute/WebsiteBackup/extract_backup`
- Auth: HTTP basic

This function starts copying the website files of the `domain` parameter
out of the named backup into a folder under the account's home
directory, and returns an `operationId` return value immediately.

**Note:**

* Poll the `WebsiteBackup::operation_status` function with the returned
  id for progress and the terminal state. The
  `WebsiteBackup::list_operations` function recovers the id if the
  client loses it.
* The extraction is non-destructive. It never overwrites an existing
  file and never activates anything. It only places a copy of the
  archived document root under the named folder.
* Because nothing live is touched, the per-account backup lock does not
  gate it and it may run alongside another operation.
* Both the folder creation and the extraction run confined to the
  account's jail wherever the account is normally confined, so a
  jailed account cannot redirect the write outside its jail.
* Pre-flight checks run synchronously and fail this call. The account
  must own the domain, the archive must exist, and the expanded archive
  must fit on disk.
* The operation runs under a two-hour wall-clock cap.
* This function requires the account's `backup` feature and is
  unavailable to demo (shared) accounts.

## Request body `application/x-www-form-urlencoded`

- object
  - `domain` string, required: The website whose files to extract from the backup. **Note:** The account must own this domain.
  - `id` string, required: Identifier of the backup to extract from, as returned by the `WebsiteBackup::list_backups` function. **Note:** The function does not check this parameter against the `domain` parameter. It locates the archive in the account's own backup directory by id alone, so an id from another of the account's sites extracts that site's files instead.
  - `path` string, required: Destination folder for the extracted files, relative to the account's home directory. **Note:** * The function creates the folder if it does not exist. It never overwrites existing files inside it. * The function strips a leading slash from this parameter and rejects any `..` segment, but it does **not** resolve symlinks inside the home directory. * The `WebsiteBackup::list_operations` function reports this destination as its `extractPath` return value.

## Response `200`

HTTP Request was successful.

- object
  - `apiversion` integer: The version of the API.
  - `func` string: The name of the method called.
  - `module` string: The name of the module called.
  - `result` object
    - `data` object: The identifier of the background operation this call started.
      - `operationId` string: Identifier of the detached operation that performs the work. **Note:** Pass it to the `WebsiteBackup::operation_status` function to poll progress. The `WebsiteBackup::list_operations` function recovers it if the client loses it.
    - `errors` string[], nullable: List of errors if the API failed.
    - `messages` string[], nullable: List of messages generated by the API.
    - `metadata` object
    - `status` 0 | 1: * `1` - Success. * `0` - Failed. Check the `errors` field for more details.
    - `warnings` string[], nullable: List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running an API.

## Changes

- **2026-09-12** `99adb57e7a5d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cpanel/apis/cpanel-uapi/changes/WebsiteBackup/extract_backup/post.md)

---

[API](https://skmtc.dev/cpanel/apis/cpanel-uapi.md) - [All operations](https://skmtc.dev/cpanel/apis/cpanel-uapi/llms.txt) - [OpenAPI document](https://skmtc.dev/cpanel/apis/cpanel-uapi/revisions/05239220da37?raw)