We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Child pages
  • UAPI Functions - Backup::restore_files
Skip to end of metadata
Go to start of metadata


This function restores an account's files.


In cPanel & WHM version 88 and later, when you disable the File Storage role, the system disables this function.


 cPanel or Webmail Session URL


This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
// Restore the user's backup file.
$Backup_restore_database = $cpanel->uapi(
    'Backup', 'restore_files',
        'backup'    => '/home/cpuser/backup_cpuser_9-10-2019.tar.gz',
        'verbose'   => '1',
        'timeout'   => '3600',


For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
# Restore the user's backup file.
my $Backup_restore_files = $cpliveapi->uapi(
    'Backup', 'restore_files',
        'backup'   => '/home/cpuser/backup_cpuser_9-10-2019.tar.gz',
        'verbose'  => '1',
        'timeout'  => '3600',


For more information, read our Guide to the LiveAPI System.

 Command Line
uapi --user=username Backup restore_files backup=/home/cpuser/backup_cpuser_9-10-2019.tar.gz verbose=1 timeout=3600


  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:


 Output (JSON)
          "data" : {
             "log_id" : "2019-09-11T18:30:49Z.1",
             "log_path" : "/home/cpuser/.cpanel/logs/restorefiles/2019-09-11T18:30:49Z.1.log"
          "status" : 1,
          "errors" : null,
          "messages" : [
             "Created the restore directory “/home/cpuser/point2”.",
             "No virus detected in upload “”.",
             "The system is extracting the archive “/home/cpuser/backup-cpuser.tld-9-10-2019_1.tar.gz”.",
             "The system successfully restored the directory “/home/cpuser/point2” from the backup file “backup-cpuser.tld-9-10-2019_1.tar.gz”."
          "warnings" : null,
          "metadata" : {}


Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.


ParameterTypeDescriptionPossible valuesExample
backup string


The backup file to upload or restore. 


  • You can only restore backup files that already exist on the server.
  • To upload a backup file, you must pass this parameter in a multipart/form-data structure. For more information about this structure, read Mozilla's POST Method documentation.


To restore multiple backup files, increment the parameter name. For example: backup-1backup-2backup-3.

A valid backup filename.

For a complete list of backup filename formats, read our Transfer or Restore a cPanel Account documentation.


For cPanel & WHM version 86 and earlier, read our Restore a Full Backup/cpmove File documentation.

 Backup filename...


 Form/data structure...
Content-Disposition: form-data; name="backup-1"; backup="backup-cpuser.tld-9-10-2019_1.tar.gz"
Content-Type: application/x-gzip

verbose Boolean

Whether to return additional information from the  /usr/local/cpanel/logs/cpbackup  log file.

This parameter defaults to 0.

  • 1 — Return.
  • 0  – Don't return.
directory string

The directory to which to restore the file.

This parameter defaults to the user's /home directory.

The full directory path for a cPanel account./home/user/example


ReturnTypeDescriptionPossible valuesExample

The log file's restoration identification (ID). 

The system uses the backup restoration's date to create this ID.

The backup restoration date, in YYYY-MM-DDTHH:mm:SS.rev human-readable format, where:

  • YYYY-MM-DD  is the file's year, month, and date timestamp.
  • HH:mm:SS is the file's hour, minute, and seconds timestamp.
  • rev is the log's revision during the current backup restoration.


log_pathstringThe log file where the system recorded the backup restoration.A valid absolute filepath.


messagesarray of stringsAn array of statements about the database's restoration.An array of strings that describe the restoration's status. 

 Click to view...
The system successfully restored the directory “/home/cpuser/point2” from the backup file “backup-cpuser.tld-9-10-2019_1.tar.gz”