List cloud backups

List backups for the signed-in client account and selected provider. This endpoint does not read current local profile directory sizes or restore a profile.

Request

GET /api/listCloudBackups
api-key: REPLACE_WITH_LOCAL_API_KEY

Keep the client running, signed in with an active VIP (Pro) membership, and authorized for both local_api and cloud sync. Copy the actual local base URL and api-key from the client API screen; the API port is dynamic and is not the browser CDP port. See Overview and authentication.

Query parameters

Parameter	Type	Required	Description
provider	string	No	Exactly oss or webdav. Defaults to the client's global cloud-sync provider.
page	integer	No	Positive integer, starting at 1; default 1. Must be within JavaScript's safe integer range.
pageSize	integer	No	1–1000; default 50.

Only these three query parameters are accepted; unknown parameters return HTTP 400. Pagination values must be positive decimal integer strings without leading zeros; empty values, 0, negatives, fractions, or out-of-range values are rejected, not silently adjusted. Each pagination parameter has its own default; they need not be supplied together.

Valid backups are deduplicated and sorted by cloudId in case-sensitive ASCII ascending order before pagination. There is no user-supplied sort parameter.

For webdav, configure the server, account, and base directory in the client first. The endpoint uses only those saved settings. Do not pass WebDAV URLs, usernames, authentication passwords, or a webdav object as parameters.

cURL

Replace both placeholders with values from the client API screen before running. These examples use Bash syntax and contain no usable credentials.

BASE_URL='http://127.0.0.1:REPLACE_WITH_API_PORT'
API_KEY='REPLACE_WITH_LOCAL_API_KEY'
curl --get "${BASE_URL}/api/listCloudBackups" \
  --header "api-key: ${API_KEY}" \
  --data-urlencode 'provider=oss' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=50'

Python

import requests

base_url = "http://127.0.0.1:REPLACE_WITH_API_PORT"
response = requests.get(
    f"{base_url}/api/listCloudBackups",
    headers={"api-key": "REPLACE_WITH_LOCAL_API_KEY"},
    params={"provider": "oss", "page": 1, "pageSize": 50},
    timeout=60,
)
response.raise_for_status()
print(response.json())

Success response

HTTP 200; all identifiers and names below are fictional.

{
  "success": true,
  "data": [
    {
      "cloudId": "8f2b6a91-3d74-4c65-9e20-5a1c7d8b9034",
      "name": "EXAMPLE_CLOUD_PROFILE",
      "provider": "oss",
      "envSizeBytes": 10485760,
      "envSizeMB": "10.00",
      "localIds": [12, 35]
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 50,
  "provider": "oss"
}

Field	Type	Meaning
success	boolean	true for a successful listing.
data	object[]	Backups on the requested page in cloudId ASCII ascending order; may be empty.
data[].cloudId	string	Cloud backup identifier, not a local profile ID.
data[].name	string	Name from cloud metadata; may be empty.
data[].provider	string	Selected oss or webdav provider.
data[].envSizeBytes	integer	Non-negative backup size in bytes from cloud metadata; unavailable or invalid size becomes 0.
data[].envSizeMB	string	envSizeBytes / 1024 / 1024, formatted to two decimal places.
data[].localIds	integer[]	Positive local profile IDs already bound to this backup and provider; empty if none match.
total	integer	Number of valid, deduplicated backups before pagination, not the page length.
page, pageSize	integer	Effective pagination values. A page past the end returns an empty data array.
provider	string	Effective provider for the whole response.

Names and sizes come from cloud metadata, not live local disk contents: OSS uses the cloud listing metadata; WebDAV uses .meta.json names and the .dat object's reported size. localIds requires the same cloudId and provider. For WebDAV it also requires the same configured server, account, and base directory; a matching cloud ID on another WebDAV configuration is not enough.

localIds indicates an association, not whether automatic cloud sync is enabled. A restored profile with automatic sync disabled can still appear here.

Use cloudId with Restore a cloud backup. Existing localIds do not make restore overwrite those profiles.

Errors

Errors produced by the new endpoint use this shape:

{
  "success": false,
  "code": "INVALID_PARAMETERS",
  "error": "Invalid request parameters"
}

HTTP	code	Meaning
400	INVALID_PARAMETERS	Unknown query parameter or invalid pagination.
400	INVALID_PROVIDER	Provider is not exactly oss or webdav.
400	WEBDAV_CONFIG_REQUIRED	Saved client WebDAV configuration is missing or invalid.
401	AUTH_REQUIRED / LOGIN_REQUIRED	Client sign-in is required. A missing or invalid api-key is also 401, from global middleware.
403	VIP_REQUIRED	Cloud VIP access is missing or expired. Missing local_api authorization also returns 403, from global middleware.
409	CLOUD_SESSION_CHANGED	The client switched accounts during the operation. Check the current account before trying again.
502	CLOUD_BACKUP_LIST_FAILED / WEBDAV_AUTH_FAILED	Cloud listing failed, or the saved WebDAV credentials were rejected.
503	CLOUD_SYNC_UNAVAILABLE	The client's cloud-sync module is unavailable.
504	REQUEST_TIMEOUT	A detected cloud transport timeout.

Existing global authentication middleware may return only success and error, with no code. Check both the HTTP status and body; see Errors and response compatibility.