---
title: "Backup - REST v2"
canonical: "https://docs.getxray.app/space/XRAYCLOUD/44578092/Backup%20-%20REST%20v2"
format: markdown
---
|  |  |
| --- | --- |
| Generate a Backup | <span style="color: #ff9900">**/api/v2/backup**</span> |
| Check backup job status | <span style="color: #ff9900">**/api/v2/backup/{jobId}/status**</span> |
| Get backup file | <span style="color: #ff9900">**/api/v2/backup/file**</span> |
| Get attachment backup file | <span style="color: #ff9900">**/api/v2/backup/file/attachment**</span> |

The first endpoint is an asynchronous call to generate a backup. Whenever this endpoint is called, a job is queued to create the backup and its id is returned. The second endpoint can be used to check the status of this job.

## Generate a Backup

When importing tests, you can use the following endpoint:

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> > ℹ️ Create a job to generate a backup.
> > ℹ️ 
> > ℹ️ <span style="color: #003366">**Request**</span>
> > ℹ️ 
> > ℹ️   
> > ℹ️ In the body of the request the following fields can be used:
> > ℹ️ 
> > ℹ️ - **projectIds **(optional): This field determines which projects to backup. This field is optional, if omitted, the backup will contain Xray information of all projects containing it.
> > ℹ️ - **modifiedSince **(optional): This field can hold a date in order for a partial backup to be generated containing only entities that were change from that date until now. This field is optional, if not supplied a full backup will be generated.
> > ℹ️ - **withAttachment** (optional): It determines if the a zip file with the attachments should also be generated.
> > ℹ️ - **excludeIssueHistory** (optional):
> > ℹ️   - If the excludeIssueHistory field is **true**, then the information in the issueHistory collection won't be included in the backup.
> > ℹ️   - If the fields are not present in the input, it's as if they had the "false" value.
> > ℹ️ - **excludeArchivedTestRuns** (optional):
> > ℹ️   - If the excludeArchivedTestRuns field is **true**, then the information in the archivedTestRuns collection won't be included in the backup.
> > ℹ️   - If the fields are not present in the input, it's as if they had the "false" value.
> > ℹ️ 
> > ℹ️ ###### <span style="color: #003366">**Example 1:**</span>
> > ℹ️ 
> > ℹ️   
> > ℹ️ **Example Input**
> > ℹ️ 
> > ℹ️ > Macro (legacy-content)
> > ℹ️ 
> > ℹ️ > Macro (legacy-content)
> 
> > ℹ️ ### <span style="color: #003366">**Responses**</span>
> > ℹ️ 
> > ℹ️ 200 OK : **application/json** : Successful. The backup job was created successfully and the Job Id is provided.  
> > ℹ️ **Example Output**
> > ℹ️ 
> > ℹ️ > Macro (legacy-content)
> > ℹ️ 
> > ℹ️ 
> > ℹ️ 400 BAD_REQUEST : **application/json : **No backup job was created.** **Another backup job is still running or was completed not long ago.  
> > ℹ️ **Example Output**
> > ℹ️ 
> > ℹ️ > Macro (legacy-content)
> > ℹ️ 
> > ℹ️   
> > ℹ️   
> > ℹ️ **401 UNAUTHORIZED: application/json: **The API token is invalid.

## Check a Backup Status

When importing tests, you can use the following endpoint:

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> |  |
> | --- |
> | Get a backup job status.<br><span style="color: #003366">**Request**</span>** **<br>###### <span style="color: #003366">**PATH PARAMETERS**</span><br>> Macro (nested-table)<br>> ✅ **Example Request**
> > ✅ 
> > ✅ curl -H "Content-Type: application/json" -X GET -H "Authorization: Bearer $token" https://xray.cloud.getxray.app/api/v2/backup/34a4106b1d0948d1aae1170cc8df3bb4/status<br>### <span style="color: #003366">**Responses**</span>** **<br>200 OK : **application/json** : The status of the backup job is returned.<br>##### **Example Output 1**<br>```
> {
>   "status": "working",
>   "progressValue": "10%"
> }
> ```<br>##### **Example Output 2**<br>```
> {
>   "status": "successful",
>   "fileUrl": "https://xray.cloud.getxray.app/api/v1/backup/file",
>   "attachmentUrl": "https://xray.cloud.getxray.app/api/v1/backup/file/attachment"
> }
> ```<br>404 BAD_REQUEST : **application/json : **No backup job with the given id was found.<br>##### **Example Output**<br>```javascript
> {
>   "error": "job not found."
> }
> ```<br>401 UNAUTHORIZED : **application/json** : The API token is not valid. |

## Download the backup file

To download the backup file, you can use the following endpoint:

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> |  |
> | --- |
> | <span style="color: #003366">**Request**</span>** **<br>> ✅ **Example Request**
> > ✅ 
> > ✅ curl -H -L "Content-Type: application/json" -X GET -H "Authorization: Bearer $token" https://xray.cloud.getxray.app/api/v2/backup/file<br>### <span style="color: #003366">**Responses**</span>** **<br>200 OK : **application/octet-stream**: The backup file is downloaded.<br>404 NOT_FOUND : **application/json : **A backup file is not available.<br>##### **Example Output**<br>```javascript
> {
>   "error": "Backup file is not available."
> }
> ```<br>401 UNAUTHORIZED : **application/json** : The API token is not valid. |

<span style="color: #172b4d">Download the attachment backup file</span>

To download the attachment backup file, you can use the following endpoint:

> Macro (rw-ui-expands-macro)
> 
> > Macro (rw-expand)
> 
> |  |
> | --- |
> | <span style="color: #003366">**Request**</span>** **<br>> ✅ **Example Request**
> > ✅ 
> > ✅ curl -H -L "Content-Type: application/json" -X GET -H "Authorization: Bearer $token" https://xray.cloud.getxray.app/api/v2/backup/file/attachment<br>### <span style="color: #003366">**Responses**</span>** **<br>200 OK : **application/octet-stream**: The backup file is downloaded.<br>404 NOT_FOUND : **application/json : **A backup file is not available.<br>##### **Example Output**<br>```javascript
> {
>   "error": "Backup file is not available."
> }
> ```<br>401 UNAUTHORIZED : **application/json** : The API token is not valid. |