--- title: Backup and restore description: 'Create, list, retrieve, and delete backups, and start, list, and cancel restores. Backup and restore endpoints require the upgraded storage engine, enabled with the --use-pacha-tree flag, and a compactor node that runs the backup and restore engine. If the storage engine is not present on the node, these endpoints return 503 Service Unavailable. All endpoints require an admin (operator) token or admin user. Backups and restores run asynchronously: starting one returns immediately with a handle t' url: https://docs.influxdata.com/influxdb3/enterprise/api/backup-and-restore/ estimated_tokens: 3292 product: InfluxDB 3 Enterprise version: enterprise publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/enterprise/api/backup-and-restore/ --- [Download InfluxDB 3 Enterprise API Spec](/openapi/influxdb3-enterprise-openapi.yml) Create, list, retrieve, and delete backups, and start, list, and cancel restores. Backup and restore endpoints require the upgraded storage engine, enabled with the `--use-pacha-tree` flag, and a compactor node that runs the backup and restore engine. If the storage engine is not present on the node, these endpoints return `503 Service Unavailable`. All endpoints require an admin (operator) token or admin user. Backups and restores run asynchronously: starting one returns immediately with a handle that you poll for status. Only one restore can run cluster-wide at a time. GET`/api/v3/enterprise/backup` ### List backups Lists all full backups. Requires an admin (operator) token. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`. This endpoint is only available in InfluxDB 3 Enterprise. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/enterprise/backup" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the list of backups. `backups`requiredobject[] All full backups. 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 500Internal server error. Listing backups failed. `data`object `error`string 503Service unavailable. The backup engine is not present on this node (not a compactor node). `data`object `error`string POST`/api/v3/enterprise/backup` ### Start a backup Registers and asynchronously starts a full backup. Returns immediately with the resolved backup name and an in-progress acknowledgement. Backups run asynchronously. Poll [List backups](#operation/list_backups) or [Get a backup](#operation/get_backup) to track progress. Requires an admin (operator) token. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`. This endpoint is only available in InfluxDB 3 Enterprise. #### Request bodyrequired Content-Type:`application/json` `force`boolean Overwrite an existing backup of the same name. `name`string The backup name. Defaults to a generated name when omitted. `type`requiredstring The backup type. Only `full` backups are supported. Allowed:`full` Example request body ```json { "force": false, "name": "nightly-backup", "type": "full" } ``` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/enterprise/backup" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"force":false,"name":"nightly-backup","type":"full"}' ``` #### Responses 202Accepted. The backup has started. `backup_name`requiredstring The resolved backup name. `status`requiredstring Example request body ```json { "backup_name": "nightly-backup", "status": "in_progress" } ``` 400 Request failed. Possible reasons: * Invalid database name * Malformed request body * Invalid timestamp precision `data`object `error`string 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 409Conflict. A backup with that name already exists and `force` is `false`, or a duplicate backup job is already in flight. `data`object `error`string 503Service unavailable. The backup engine is not present on this node (not a compactor node). `data`object `error`string DELETE`/api/v3/enterprise/backup` ### Cancel a running backup Cancels an in-progress backup job by name. Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`. This endpoint is only available in InfluxDB 3 Enterprise. #### Request bodyrequired Content-Type:`application/json` `name`requiredstring The name of the backup job to cancel. Example request body ```json { "name": "nightly-backup" } ``` Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/enterprise/backup" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"name":"nightly-backup"}' ``` #### Responses 200Success. The cancellation has been accepted. `backup_name`requiredstring The cancelled backup name. Example request body ```json { "backup_name": "nightly-backup" } ``` 400 Request failed. Possible reasons: * Invalid database name * Malformed request body * Invalid timestamp precision `data`object `error`string 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not found. No backup is running with that name. `data`object `error`string 503Service unavailable. The backup engine is not present on this node (not a compactor node). `data`object `error`string GET`/api/v3/enterprise/backup/{name}` ### Get a backup Returns a single backup’s manifest. Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`. This endpoint is only available in InfluxDB 3 Enterprise. #### Parameters ##### Path parameters `name`requiredstring The backup name. URL-encoded names are decoded by the server. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/enterprise/backup/{name}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the backup manifest. 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not found. No backup exists with that name. `data`object `error`string 503Service unavailable. The backup engine is not present on this node (not a compactor node). `data`object `error`string DELETE`/api/v3/enterprise/backup/{name}` ### Delete a backup Deletes a backup by name. Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`. This endpoint is only available in InfluxDB 3 Enterprise. #### Parameters ##### Path parameters `name`requiredstring The backup name. URL-encoded names are decoded by the server. Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/enterprise/backup/{name}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. The backup has been deleted. `backup_name`requiredstring The deleted backup name. `type`requiredstring Example request body ```json { "backup_name": "nightly-backup", "type": "full" } ``` 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not found. No backup exists with that name. `data`object `error`string 409Conflict. The backup is in progress and cannot be deleted, or the backup chain is in a conflicting state. `data`object `error`string 503Service unavailable. The backup engine is not present on this node (not a compactor node). `data`object `error`string GET`/api/v3/enterprise/restore` ### List restores Lists every restore for the cluster, newest first, including in-flight and completed restores. Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`. This endpoint is only available in InfluxDB 3 Enterprise. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/enterprise/restore" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the list of restores. `restores`requiredobject[] All restores, newest first. 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 500Internal server error. Listing restores failed. `data`object `error`string 503Service unavailable. The restore engine is not present on this node. `data`object `error`string POST`/api/v3/enterprise/restore` ### Start a restore Registers and asynchronously starts a restore from a named backup. Returns a `restore_id` handle for tracking and cancellation. Restores run asynchronously. Poll [Get a restore](#operation/get_restore) to track progress. Only one restore can run cluster-wide at a time; if a restore is already running, this endpoint returns `409 Conflict`. Requires an admin (operator) token. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`. This endpoint is only available in InfluxDB 3 Enterprise. #### Request bodyrequired Content-Type:`application/json` `backup_name`requiredstring The name of the backup to restore from. Must not be empty. Example request body ```json { "backup_name": "nightly-backup" } ``` Example request[Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/enterprise/restore" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"backup_name":"nightly-backup"}' ``` #### Responses 202Accepted. The restore has started. `restore_id`requiredstring The handle used to track or cancel the restore. `status`requiredstring Example request body ```json { "restore_id": "01J8X9Z0ABCDEF", "status": "in_progress" } ``` 400Bad request. `backup_name` is empty. `data`object `error`string 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 409Conflict. A restore is already running. Only one restore can run at a time. `data`object `error`string 503Service unavailable. The restore engine is not present on this node, or the restore lease could not be acquired. `data`object `error`string GET`/api/v3/enterprise/restore/{id}` ### Get a restore Reports a restore’s state by `restore_id`. Reads the persisted manifest, so it works for in-flight and completed restores. Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`. This endpoint is only available in InfluxDB 3 Enterprise. #### Parameters ##### Path parameters `id`requiredstring The `restore_id` returned when the restore started. Example request[Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/enterprise/restore/{id}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Success. Returns the restore status. `backup_name`requiredstring The source backup name. `completed_at`string \ The completion timestamp. Null when the restore is not complete. `created_at`requiredstring \ When the restore started. `restore_id`requiredstring The restore handle. `status`requiredstring `total_files`requiredinteger \ The number of files. `total_size_bytes`requiredinteger \ The total size in bytes. Example request body ```json { "backup_name": "nightly-backup", "completed_at": null, "created_at": "2025-06-16T03:00:00Z", "restore_id": "01J8X9Z0ABCDEF", "status": "in_progress", "total_files": 128, "total_size_bytes": 524288000 } ``` 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not found. No restore exists with that ID. `data`object `error`string 503Service unavailable. The restore engine is not present on this node. `data`object `error`string DELETE`/api/v3/enterprise/restore/{id}` ### Cancel a running restore Cancels an in-flight restore by `restore_id`. Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node. This endpoint is only available in InfluxDB 3 Enterprise. #### Parameters ##### Path parameters `id`requiredstring The `restore_id` returned when the restore started. Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/enterprise/restore/{id}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204No content. The cancellation has been accepted. 401Unauthorized access. `data`object `error`string 403Access denied. `data`object `error`string 404Not found. No restore exists with that ID, the restore is already completed, or the restore engine is not present on this node. `data`object `error`string #### Related * [InfluxDB 3 API client libraries](/influxdb3/enterprise/reference/client-libraries/v3/)