List backups

Authorization

A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:

Service Token Accesses read_backups

OAuth Scopes

Resource	Scopes
Organization	read_backups
Database	read_backups
Branch	read_backups

GET /organizations/{organization}/databases/{database}/branches/{branch}/backups

List backups

cURL

curl --request GET \
  --url https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches/{branch}/backups \
  --header 'Authorization: Bearer <token>'

200

{
  "type": "<string>",
  "current_page": 123,
  "next_page": 123,
  "next_page_url": "<string>",
  "prev_page": 123,
  "prev_page_url": "<string>",
  "data": [
    {
      "id": "<string>",
      "name": "<string>",
      "size": 123,
      "estimated_storage_cost": 123,
      "created_at": "<string>",
      "updated_at": "<string>",
      "started_at": "<string>",
      "expires_at": "<string>",
      "completed_at": "<string>",
      "deleted_at": "<string>",
      "pvc_size": 123,
      "protected": true,
      "required": true,
      "restored_branches": [
        {
          "id": "<string>",
          "name": "<string>",
          "created_at": "<string>",
          "updated_at": "<string>",
          "deleted_at": "<string>"
        }
      ],
      "actor": {
        "id": "<string>",
        "display_name": "<string>",
        "avatar_url": "<string>"
      },
      "backup_policy": {
        "id": "<string>",
        "display_name": "<string>",
        "name": "<string>",
        "retention_value": 123,
        "retention_unit": "<string>",
        "frequency_value": 123,
        "frequency_unit": "<string>",
        "schedule_time": "<string>",
        "schedule_day": 123,
        "schedule_week": 123,
        "created_at": "<string>",
        "updated_at": "<string>",
        "last_ran_at": "<string>",
        "next_run_at": "<string>",
        "required": true
      },
      "schema_snapshot": {
        "id": "<string>",
        "name": "<string>",
        "created_at": "<string>",
        "updated_at": "<string>",
        "linted_at": "<string>",
        "url": "<string>"
      },
      "database_branch": {
        "id": "<string>",
        "name": "<string>",
        "created_at": "<string>",
        "updated_at": "<string>",
        "deleted_at": "<string>"
      }
    }
  ]
}

Authorizations

Authorization · string · header · required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

organization · string · required

The name of the organization the branch belongs to

database · string · required

The name of the database the branch belongs to

branch · string · required

The name of the branch

Query Parameters

all · boolean

Whether to include all backups, including deleted ones

state · enum<string>

Filter backups by state

Available options: pending, running, success, failed, canceled, ignored

policy · string

Filter backups by backup policy ID

from · string

Filter backups started after this date (e.g. 2023-01-01T00:00:00Z)

to · string

Filter backups started before this date (e.g. 2023-01-31T23:59:59Z)

running_at · string

Filter backups that are running during a specific time (e.g. 2023-01-01T00:00:00Z..2023-01-01T23:59:59Z)

production · boolean

Filter backups by production branch

page · integer · default: 1

If provided, specifies the page offset of returned results

per_page · integer · default: 25

If provided, specifies the number of returned results

Response

200

application/json

Returns database branch backups

type · string · required

The response type. Always "list" for paginated responses.

current_page · integer · required

The current page number

next_page · integer | null · required

The next page number, or null when this is the last page

next_page_url · string | null · required

The next page of results, or null when this is the last page

prev_page · integer | null · required

The previous page number, or null when this is the first page

prev_page_url · string | null · required

The previous page of results, or null when this is the first page

data · object[] · required

Show child attributes