--- title: "List backups" method: GET path: "/organizations/{organization}/databases/{database}/branches/{branch}/backups" tags: ["Backups"] --- # List backups `GET /organizations/{organization}/databases/{database}/branches/{branch}/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` | ## Path parameters - `organization` string, required - `database` string, required - `branch` string, required ## Query parameters - `all` boolean - `state` 'pending' | 'running' | 'success' | 'failed' | 'canceled' | 'ignored' - `policy` string - `from` string - `to` string - `running_at` string - `production` boolean - `page` integer - `per_page` integer ## Response `200` Returns database branch backups - object - `type` string, required — The response type. Always "list" for paginated responses. - `current_page` integer, required — The current page number - `per_page` integer, required — The maximum number of results per page - `next_page` integer, nullable, required — The next page number, or null when this is the last page - `next_page_url` string, nullable, required — The next page of results, or null when this is the last page - `prev_page` integer, nullable, required — The previous page number, or null when this is the first page - `prev_page_url` string, nullable, required — The previous page of results, or null when this is the first page - `total_count` integer, required — The total number of matching results - `total_pages` integer, required — The total number of pages of matching results - `data` object[], required - `id` string, required — The ID of the backup - `name` string, required — The name of the backup - `state` 'pending' | 'running' | 'success' | 'failed' | 'canceled' | 'ignored', required — The current state of the backup - `size` integer, required — The size of the backup in bytes - `estimated_storage_cost` number, required — The estimated storage cost of the backup - `created_at` string, required — When the backup was created - `updated_at` string, required — When the backup was last updated - `started_at` string, nullable, required — When the backup started - `expires_at` string, nullable, required — When the backup expires - `completed_at` string, nullable, required — When the backup completed - `deleted_at` string, nullable, required — When the backup was deleted - `pvc_size` integer, required — Size of the PVC used for the backup - `uncompressed_size` integer, required — The uncompressed (logical) size of the backup in bytes - `protected` boolean, required — Whether or not the backup is protected from deletion - `required` boolean, required — Whether or not the backup policy is required - `restored_branches` object[], required - `id` string, required — The ID for the resource - `name` string, required — The name for the resource - `created_at` string, required — When the resource was created - `updated_at` string, required — When the resource was last updated - `deleted_at` string, nullable, required — When the resource was deleted, if deleted - `actor` object, nullable, required - `id` string, required — The ID of the actor - `display_name` string, required — The name of the actor - `avatar_url` string, required — The URL of the actor's avatar - `backup_policy` object, nullable - `id` string, required — The ID of the backup policy - `display_name` string, required — The display name of the backup policy - `name` string, required — The name of the backup policy - `target` 'production' | 'development', required — Whether the policy is for production or development branches - `retention_value` integer, required — A number value for the retention period of the backup policy - `retention_unit` string, required — The unit for the retention period of the backup policy - `frequency_value` integer, required — A number value for the frequency of the backup policy - `frequency_unit` string, required — The unit for the frequency of the backup policy - `schedule_time` string, required — The time of day that the backup is scheduled, in HH:MM format - `schedule_day` integer, nullable, required — Day of the week that the backup is scheduled. 0 is Sunday, 6 is Saturday - `schedule_week` integer, nullable, required — Week of the month that the backup is scheduled. 0 is the first week, 3 is the fourth week - `created_at` string, required — When the backup policy was created - `updated_at` string, required — When the backup policy was last updated - `last_ran_at` string, nullable, required — When the backup was last run - `next_run_at` string, nullable, required — When the backup will next run - `required` boolean, required — Whether the policy is a required system backup - `schema_snapshot` object, nullable - `id` string, required — The ID of the schema snapshot - `name` string, required — The name of the schema snapshot - `created_at` string, required — When the schema snapshot was created - `updated_at` string, required — When the schema snapshot was last updated - `linted_at` string, nullable, required — When the schema snapshot was last linted - `url` string, required — The URL to the schema snapshot in the PlanetScale app - `database_branch` object, nullable - `id` string, required — The ID for the resource - `name` string, required — The name for the resource - `created_at` string, required — When the resource was created - `updated_at` string, required — When the resource was last updated - `deleted_at` string, nullable, required — When the resource was deleted, if deleted ## Other responses - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `500` — Internal Server Error ## Changes - **2026-08-18** `249942995489` — 2 info - added the required property `total_count` to the response with the `200` status - added the required property `total_pages` to the response with the `200` status - **2026-08-11** `4b2e4f05bda2` — 1 info - added the required property `per_page` to the response with the `200` status - **2026-07-08** `fa19f3305241` — 1 info - added the required property `data/items/uncompressed_size` to the response with the `200` status - **2026-06-01** `72506953f367` — 22 breaking, 2 info - the response property `data/items/actor` became nullable for the status `200` - the response property `data/items/backup_policy` became nullable for the status `200` - the response property `data/items/backup_policy/last_ran_at` became nullable for the status `200` - the response property `data/items/backup_policy/next_run_at` became nullable for the status `200` - …20 more - **2025-12-09** `d710019068fb` — 2 breaking - for the `query` request parameter `page`, the type/format was changed from `number`/`` to `integer`/`` - for the `query` request parameter `per_page`, the type/format was changed from `number`/`` to `integer`/`` [Full history](https://skmtc.dev/planetscale/apis/planetscale-api/changes/organizations/:organization/databases/:database/branches/:branch/backups/get.md) --- [API](https://skmtc.dev/planetscale/apis/planetscale-api.md) · [All operations](https://skmtc.dev/planetscale/apis/planetscale-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/planetscale/planetscale-api/revisions/6d28c038c4fd/schema)