Backup and restore

Download InfluxDB 3 Enterprise API Spec

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
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/backup" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the list of backups.
backups required object[]
All full backups.
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
500 Internal server error. Listing backups failed.
data object
error string
503 Service 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 or Get a 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 body required

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 required string
The backup type. Only full backups are supported.
Allowed: full
Example request body
{
  "force": false,
  "name": "nightly-backup",
  "type": "full"
}
Example request Ask AI about this
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

202 Accepted. The backup has started.
backup_name required string
The resolved backup name.
status required string
Example request body
{
  "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
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
409 Conflict. A backup with that name already exists and force is false, or a duplicate backup job is already in flight.
data object
error string
503 Service 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 body required

Content-Type: application/json
name required string
The name of the backup job to cancel.
Example request body
{
  "name": "nightly-backup"
}
Example request Ask AI about this
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

200 Success. The cancellation has been accepted.
backup_name required string
The cancelled backup name.
Example request body
{
  "backup_name": "nightly-backup"
}
400

Request failed. Possible reasons:

  • Invalid database name
  • Malformed request body
  • Invalid timestamp precision
data object
error string
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No backup is running with that name.
data object
error string
503 Service 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 required string
The backup name. URL-encoded names are decoded by the server.
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/backup/{name}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the backup manifest.
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No backup exists with that name.
data object
error string
503 Service 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 required string
The backup name. URL-encoded names are decoded by the server.
Example request Ask AI about this
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/backup/{name}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The backup has been deleted.
backup_name required string
The deleted backup name.
type required string
Example request body
{
  "backup_name": "nightly-backup",
  "type": "full"
}
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No backup exists with that name.
data object
error string
409 Conflict. The backup is in progress and cannot be deleted, or the backup chain is in a conflicting state.
data object
error string
503 Service 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
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/restore" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the list of restores.
restores required object[]
All restores, newest first.
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
500 Internal server error. Listing restores failed.
data object
error string
503 Service 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 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 body required

Content-Type: application/json
backup_name required string
The name of the backup to restore from. Must not be empty.
Example request body
{
  "backup_name": "nightly-backup"
}
Example request Ask AI about this
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

202 Accepted. The restore has started.
restore_id required string
The handle used to track or cancel the restore.
status required string
Example request body
{
  "restore_id": "01J8X9Z0ABCDEF",
  "status": "in_progress"
}
400 Bad request. backup_name is empty.
data object
error string
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
409 Conflict. A restore is already running. Only one restore can run at a time.
data object
error string
503 Service 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 required string
The restore_id returned when the restore started.
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/restore/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the restore status.
backup_name required string
The source backup name.
completed_at string <date-time>
The completion timestamp. Null when the restore is not complete.
created_at required string <date-time>
When the restore started.
restore_id required string
The restore handle.
status required string
total_files required integer <int64>
The number of files.
total_size_bytes required integer <int64>
The total size in bytes.
Example request body
{
  "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
}
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not found. No restore exists with that ID.
data object
error string
503 Service 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 required string
The restore_id returned when the restore started.
Example request Ask AI about this
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/restore/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 No content. The cancellation has been accepted.
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
404 Not 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

Was this page helpful?

Thank you for your feedback!