List backups

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

{
  "current_page": 123,
  "next_page": 123,
  "next_page_url": "<string>",
  "prev_page": 123,
  "prev_page_url": "<string>",
  "data": [
    {
      "id": "<string>",
      "name": "<string>",
      "state": "pending",
      "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>",
        "name": "<string>",
        "target": "production",
        "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>"
      }
    }
  ]
}

Backups

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 --request GET \
  --url https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches/{branch}/backups \
  --header 'Authorization: <api-key>'

{
  "current_page": 123,
  "next_page": 123,
  "next_page_url": "<string>",
  "prev_page": 123,
  "prev_page_url": "<string>",
  "data": [
    {
      "id": "<string>",
      "name": "<string>",
      "state": "pending",
      "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>",
        "name": "<string>",
        "target": "production",
        "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

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)

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

number

default:1

If provided, specifies the page offset of returned results

per_page

number

default:25

If provided, specifies the number of returned results

Response

Returns database branch backups

current_page

integer

required

The current page number

next_page

integer

required

The next page number

next_page_url

string

required

The next page of results

prev_page

integer

required

The previous page number

prev_page_url

string

required

The previous page of results

data

object[]

required

Show child attributes

data.id

string

required

The ID of the backup

data.name

string

required

The name of the backup

data.state

enum<string>

required

The current state of the backup

Available options:

pending,

running,

success,

failed,

canceled,

ignored

data.size

integer

required

The size of the backup in bytes

data.estimated_storage_cost

number

required

The estimated storage cost of the backup

data.created_at

string

required

When the backup was created

data.updated_at

string

required

When the backup was last updated

data.started_at

string

required

When the backup started

data.expires_at

string

required

When the backup expires

data.completed_at

string

required

When the backup completed

data.deleted_at

string

required

When the backup was deleted

data.pvc_size

integer

required

Size of the PVC used for the backup

data.protected

boolean

required

Whether or not the backup is protected from deletion

data.required

boolean

required

Whether or not the backup policy is required

data.restored_branches

object[]

required

Show child attributes

data.restored_branches.id

string

required

The ID for the resource

data.restored_branches.name

string

required

The name for the resource

data.restored_branches.created_at

string

required

When the resource was created

data.restored_branches.updated_at

string

required

When the resource was last updated

data.restored_branches.deleted_at

string

required

When the resource was deleted, if deleted

data.actor

object

required

Show child attributes

data.actor.id

string

required

The ID of the actor

data.actor.display_name

string

required

The name of the actor

data.actor.avatar_url

string

required

The URL of the actor's avatar

data.backup_policy

object

required

Show child attributes

data.backup_policy.id

string

required

The ID of the backup policy

data.backup_policy.name

string

required

The name of the backup policy

data.backup_policy.target

enum<string>

required

Whether the policy is for production or development branches

Available options:

production,

development

data.backup_policy.retention_value

integer

required

A number value for the retention period of the backup policy

data.backup_policy.retention_unit

string

required

The unit for the retention period of the backup policy

data.backup_policy.frequency_value

integer

required

A number value for the frequency of the backup policy

data.backup_policy.frequency_unit

string

required

The unit for the frequency of the backup policy

data.backup_policy.schedule_time

string

required

The time of day that the backup is scheduled, in HH:MM format

data.backup_policy.schedule_day

integer

required

Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday

data.backup_policy.schedule_week

integer

required

Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week

data.backup_policy.created_at

string

required

When the backup policy was created

data.backup_policy.updated_at

string

required

When the backup policy was last updated

data.backup_policy.last_ran_at

string

required

When the backup was last run

data.backup_policy.next_run_at

string

required

When the backup will next run

data.backup_policy.required

boolean

required

Whether the policy is a required system backup

data.schema_snapshot

object

required

Show child attributes

data.schema_snapshot.id

string

required

The ID of the schema snapshot

data.schema_snapshot.name

string

required

The name of the schema snapshot

data.schema_snapshot.created_at

string

required

When the schema snapshot was created

data.schema_snapshot.updated_at

string

required

When the schema snapshot was last updated

data.schema_snapshot.linted_at

string

required

When the schema snapshot was last linted

data.schema_snapshot.url

string

required

The URL to the schema snapshot in the PlanetScale app

data.database_branch

object

required

Show child attributes

data.database_branch.id

string

required

The ID for the resource

data.database_branch.name

string

required

The name for the resource

data.database_branch.created_at

string

required

When the resource was created

data.database_branch.updated_at

string

required

When the resource was last updated

data.database_branch.deleted_at

string

required

When the resource was deleted, if deleted

List audit logs

Create a backup

⌘I

Introduction

Webhooks in PlanetScale

Authentication

General API endpoints

Postgres API endpoints

Vitess API endpoints

List backups

Authorization

Authorizations

Path Parameters

Query Parameters

Response