---
title: "Create a backup"
method: POST
path: "/organizations/{organization}/databases/{database}/branches/{branch}/backups"
tags: ["Backups"]
---

# Create a backup

`POST /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**
 `write_backups`

**OAuth Scopes**

 | Resource | Scopes |
| :------- | :---------- |
| Organization | `write_backups` |
| Database | `write_backups` |
| Branch | `write_backups` |

## Path parameters

- `organization` string, required
- `database` string, required
- `branch` string, required

## Request body

- object
  - `name` string — Name for the backup
  - `retention_unit` 'hour' | 'day' | 'week' | 'month' | 'year' — Unit for the retention period of the backup
  - `retention_value` integer — Value between `1` and `1000` for the retention period of the backup (i.e retention_value `6` and retention_unit `hour` means 6 hours)
  - `emergency` boolean — Whether the backup is an immediate backup that may affect database performance. Emergency backups are only supported for PostgreSQL databases.

## Response `201`

Returns the created database branch backup

- object
  - `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-07-08** `fa19f3305241` — 1 info
  - added the required property `uncompressed_size` to the response with the `201` status
- **2026-06-01** `72506953f367` — 18 breaking, 1 info
  - the response property `actor` became nullable for the status `201`
  - the response property `backup_policy` became nullable for the status `201`
  - the response property `backup_policy/last_ran_at` became nullable for the status `201`
  - the response property `backup_policy/next_run_at` became nullable for the status `201`
  - …15 more
- **2025-12-09** `d710019068fb` — 1 breaking
  - the `retention_value` request property type/format changed from `number`/`` to `integer`/``
- **2025-12-04** `5e881928d77a` — 2 breaking, 11 info
  - the `backup_policy/schedule_day` response's property type/format changed from `string`/`` to `number`/`` for status `201`
  - the `backup_policy/schedule_week` response's property type/format changed from `string`/`` to `number`/`` for status `201`
  - removed the `0.00` enum value from the `backup_policy/schedule_day` response property for the response status `201`
  - removed the `0.00` enum value from the `backup_policy/schedule_week` response property for the response status `201`
  - …9 more

[Change history](https://skmtc.dev/planetscale/apis/planetscale-api/changes/organizations/:organization/databases/:database/branches/:branch/backups/post.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)