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.


 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 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 path for a directory on the 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 represents the year.
  • MM represents the month.
  • DD represents the date.
  • HH represents the hour.
  • mm represents the minute.
  • SS represents the second.
  • rev represents 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”