---
operationId: "restoreSnapshot"
method: "POST"
path: "/projects/{project_id}/snapshots/{snapshot_id}/restore"
tag: "snapshots"
stability: "beta"
interfaces: ["api", "sdk", "console"]
---
> API Reference / Snapshots / Restore snapshot

## POST /projects/{project_id}/snapshots/{snapshot_id}/restore

Restores the specified snapshot to a new branch,
and optionally finalizes the restore operation to replace the original branch.

**Note**: This endpoint is currently in Beta.


### Parameters

- `project_id` (string, path, required)
  The Neon project ID
- `snapshot_id` (string, path, required)
  The snapshot ID
- `name` (string, query, optional)
  DEPRECATED. Use the `name` field in the request body instead.
  A name for the newly restored branch. If omitted, a default name will be generated.
  

### Request body

- `name` (string, optional)
  A name for the newly restored branch.
  If omitted, a default name will be generated.
  
- `target_branch_id` (string, optional)
  The ID of the branch to restore the snapshot into.
  If not specified, the branch from which the snapshot was originally
  created (`snapshot.source_branch_id`) will be used.
  
- `finalize_restore` (boolean, optional)
  Set to `true` to finalize the restore operation immediately.
  This will complete the restore and move any associated computes to the new branch,
  similar to the `finalizeRestoreBranch` operation.
  Defaults to `false` to allow previewing the restored snapshot data first.
  
  Default: `false`

### Response (200)

- `branch` (object, optional)
  - `id` (string, required)
    The branch ID. This value is generated when a branch is created. A `branch_id` value has a `br` prefix. For example: `br-small-term-683261`.
    
  - `project_id` (string, required)
    The ID of the project to which the branch belongs
    
  - `parent_id` (string, optional)
    The `branch_id` of the parent branch
    
  - `parent_lsn` (string, optional)
    The Log Sequence Number (LSN) on the parent branch from which this branch was created.
    When restoring a branch using the `POST /projects/{project_id}/branches/{branch_id}/restore` endpoint,
    this value isn’t finalized until all operations related to the restore have completed successfully.
    
  - `parent_timestamp` (string, optional, format: date-time)
    The point in time on the parent branch from which this branch was created.
    When restoring a branch using the `POST /projects/{project_id}/branches/{branch_id}/restore` endpoint,
    this value isn’t finalized until all operations related to the restore have completed successfully.
    After all the operations completed, this value might stay empty.
    
  - `name` (string, required)
    The branch name
    
  - `current_state` (string, required)
    The branch’s state, indicating if it is initializing, ready for use, or archived.
      * 'init' - the branch is being created but is not available for querying.
      * 'resetting' - the branch is being reset to a specific point in time or LSN and is not yet available for querying.
      * 'ready' - the branch is fully operational and ready for querying. Expect normal query response times.
      * 'archived' - the branch is stored in cost-effective archival storage. Expect slow query response times.
    
  - `pending_state` (string, optional)
    The branch’s state, indicating if it is initializing, ready for use, or archived.
      * 'init' - the branch is being created but is not available for querying.
      * 'resetting' - the branch is being reset to a specific point in time or LSN and is not yet available for querying.
      * 'ready' - the branch is fully operational and ready for querying. Expect normal query response times.
      * 'archived' - the branch is stored in cost-effective archival storage. Expect slow query response times.
    
  - `state_changed_at` (string, required, format: date-time)
    A UTC timestamp indicating when the `current_state` began
    
  - `logical_size` (integer, optional, format: int64)
    The logical size of the branch, in bytes
    
  - `creation_source` (string, required)
    The branch creation source
    
  - `primary` (boolean, optional, deprecated)
    DEPRECATED. Use `default` field.
    Whether the branch is the project's primary branch
    
  - `default` (boolean, required)
    Whether the branch is the project's default branch
    
  - `protected` (boolean, required)
    Whether the branch is protected
    
  - `cpu_used_sec` (integer, required, deprecated, format: int64)
    CPU seconds used by all of the branch's compute endpoints, including deleted ones.
    This value is reset at the beginning of each billing period.
    Examples:
    1. A branch that uses 1 CPU for 1 second is equal to `cpu_used_sec=1`.
    2. A branch that uses 2 CPUs simultaneously for 1 second is equal to `cpu_used_sec=2`.
    
  - `compute_time_seconds` (integer, required, format: int64)
  - `active_time_seconds` (integer, required, format: int64)
  - `written_data_bytes` (integer, required, format: int64)
  - `data_transfer_bytes` (integer, required, format: int64)
  - `created_at` (string, required, format: date-time)
    A timestamp indicating when the branch was created
    
  - `updated_at` (string, required, format: date-time)
    A timestamp indicating when the branch was last updated
    
  - `ttl_interval_seconds` (integer, optional)
    The time-to-live (TTL) duration originally configured for the branch, in seconds. This read-only value represents the interval between the time `expires_at` was set and the expiration timestamp itself. It is preserved to ensure the same TTL duration is reapplied when resetting the branch from its parent, and only updates when a new `expires_at` value is set.
    
    Access to this feature is currently limited to participants in the Early Access Program.
    
  - `expires_at` (string, optional, format: date-time)
    The timestamp when the branch is scheduled to expire and be automatically deleted. Must be set by the client following the [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) format with precision up to seconds (such as 2025-06-09T18:02:16Z). Deletion is performed by a background job and may not occur exactly at the specified time.
    
    Access to this feature is currently limited to participants in the Early Access Program.
    
  - `last_reset_at` (string, optional, format: date-time)
    A timestamp indicating when the branch was last reset
    
  - `created_by` (object, optional)
    The resolved user model that contains details of the user/org/integration/api_key used for branch creation. This field is filled only in listing/get/create/get/update/delete methods, if it is empty when calling other handlers, it does not mean that it is empty in the system.
    
    - `name` (string, optional)
      The name of the user.
    - `image` (string, optional)
      The URL to the user's avatar image.
  - `init_source` (string, optional)
    The source of initialization for the branch. Valid values are `schema-only` and `parent-data` (default).
      * `schema-only` - creates a new root branch containing only the schema. Use `parent_id` to specify the source branch. Optionally, you can provide `parent_lsn` or `parent_timestamp` to branch from a specific point in time or LSN. These fields define which branch to copy the schema from and at what point—they do not establish a parent-child relationship between the `parent_id` branch and the new schema-only branch.
      * `parent-data` - creates the branch with both schema and data from the parent.
    
  - `restore_status` (string, optional)
    Could be `restored`, `finalized` or `detaching`.
    A `restored` branch becomes permanently `finalized` when you call `finalizeRestoreBranch`
    A `restored` or `finalized` branch may begin `detaching` as a one-time performance optimisation, after which it will continue in its original state
    
  - `restored_from` (string, optional)
    ID of the snapshot that was the restore source for this branch
    
  - `restored_as` (string, optional)
    ID of the target branch which was replaced when this branch was restored
    
  - `restricted_actions` (array, optional)
    A list of actions that are currently restricted for this branch and the reason why.
    
    - `name` (string, required)
      The name of a restricted action. Possible values include `restore`, `delete-rw-endpoint`.
      
    - `reason` (string, required)
      A human-readable explanation of why the action is restricted.
      
  - `recovery` (object, optional)
    Recovery information for a deleted branch. Only present when listing deleted branches
    with `include_deleted=true`.
    
    This is part of the Branch Recovery feature, which is in preview and not available to all users.
    
    - `deleted_at` (string, required, format: date-time)
      Timestamp when the branch was deleted
      
    - `recoverable_until` (string, required, format: date-time)
      Timestamp when the recovery window expires and the branch will be permanently deleted
      
    - `deletion_method` (string, required)
      How the branch was deleted: 'user' for manual deletion, 'ttl' for TTL expiration
      
      Possible values: `user`, `ttl`
- `endpoints` (array, optional)
  - `host` (string, required)
    The hostname of the compute endpoint. This is the hostname specified when connecting to a Neon database.
    
  - `id` (string, required)
    The compute endpoint ID. Compute endpoint IDs have an `ep-` prefix. For example: `ep-little-smoke-851426`
    
  - `name` (string, optional)
    Optional name of the compute endpoint
    
  - `project_id` (string, required)
    The ID of the project to which the compute endpoint belongs
    
  - `branch_id` (string, required)
    The ID of the branch that the compute endpoint is associated with
    
  - `autoscaling_limit_min_cu` (number, required)
    The minimum number of Compute Units
    
  - `autoscaling_limit_max_cu` (number, required)
    The maximum number of Compute Units
    
  - `region_id` (string, required)
    The region identifier
    
  - `type` (string, required)
    The compute endpoint type. Either `read_write` or `read_only`.
    
    Possible values: `read_only`, `read_write`
  - `current_state` (string, required)
    The state of the compute endpoint
    
    Possible values: `init`, `active`, `idle`
  - `pending_state` (string, optional)
    The state of the compute endpoint
    
    Possible values: `init`, `active`, `idle`
  - `settings` (object, required)
    A collection of settings for a compute endpoint
    - `pg_settings` (object, optional)
      A raw representation of Postgres settings
    - `pgbouncer_settings` (object, optional, deprecated)
      DEPRECATED. PgBouncer settings for the compute endpoint. This field is deprecated and will be removed after 2026-06-20.
      
    - `preload_libraries` (object, optional)
      The shared libraries to preload into the project's compute instances.
      
      - `use_defaults` (boolean, optional)
      - `enabled_libraries` (array, optional)
  - `pooler_enabled` (boolean, required, deprecated)
    DEPRECATED. Whether to enable connection pooling for the compute endpoint.
    The recommended way to enable connection pooling is to append `-pooler` to the endpoint ID in the connection string.
    See [How to use connection pooling](https://neon.com/docs/connect/connection-pooling#how-to-use-connection-pooling)
    
  - `pooler_mode` (string, required, deprecated)
    DEPRECATED. The connection pooler mode. This field is deprecated and will be removed after 2026-06-20.
    
    Possible values: `transaction`
  - `disabled` (boolean, required)
    Whether to restrict connections to the compute endpoint.
    Enabling this option schedules a suspend compute operation.
    A disabled compute endpoint cannot be enabled by a connection or
    console action.
    
  - `passwordless_access` (boolean, required)
    Whether to permit passwordless access to the compute endpoint
    
  - `last_active` (string, optional, format: date-time)
    A timestamp indicating when the compute endpoint was last active
    
  - `creation_source` (string, required)
    The compute endpoint creation source
    
  - `created_at` (string, required, format: date-time)
    A timestamp indicating when the compute endpoint was created
    
  - `updated_at` (string, required, format: date-time)
    A timestamp indicating when the compute endpoint was last updated
    
  - `started_at` (string, optional, format: date-time)
    A timestamp indicating when the compute endpoint was last started
    
  - `suspended_at` (string, optional, format: date-time)
    A timestamp indicating when the compute endpoint was last suspended
    
  - `proxy_host` (string, required)
    DEPRECATED. Use the "host" property instead.
    
  - `suspend_timeout_seconds` (integer, required, format: int64)
    Duration of inactivity in seconds after which the compute endpoint is
    automatically suspended. The value `0` means use the default value.
    The value `-1` means never suspend. The default value is `300` seconds (5 minutes).
    The minimum value is `60` seconds (1 minute).
    The maximum value is `604800` seconds (1 week). For more information, see
    [Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).
    
  - `provisioner` (string, required)
    The Neon compute provisioner.
    Specify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.
    
    Provisioner can be one of the following values:
    * k8s-pod
    * k8s-neonvm
    * serverless-platform
    
    Clients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.
    
  - `compute_release_version` (string, optional)
    Attached compute's release version number.
    
- `operations` (array, optional)
  - `id` (string, required, format: uuid)
    The operation ID
  - `project_id` (string, required)
    The Neon project ID
  - `branch_id` (string, optional)
    The branch ID
  - `endpoint_id` (string, optional)
    The endpoint ID
  - `action` (string, required)
    The action performed by the operation
    Possible values: `create_compute`, `create_timeline`, `start_compute`, `suspend_compute`, `apply_config`, `check_availability`, `delete_timeline`, `create_branch`, `import_data`, `tenant_ignore`, `tenant_attach`, `tenant_detach`, `tenant_detach_safekeepers`, `tenant_attach_safekeepers`, `tenant_reattach`, `replace_safekeeper`, `disable_maintenance`, `apply_storage_config`, `prepare_secondary_pageserver`, `switch_pageserver`, `detach_parent_branch`, `timeline_archive`, `timeline_unarchive`, `start_reserved_compute`, `sync_dbs_and_roles_from_compute`, `apply_schema_from_branch`, `timeline_mark_invisible`, `timeline_update_protected_config`, `prewarm_replica`, `promote_replica`, `set_storage_non_dirty`, `swap_binding_id`, `finalize_migration`, `mark_migration_prepared`, `update_catalog`, `epc_sync`
  - `status` (string, required)
    The status of the operation
    Possible values: `scheduling`, `running`, `finished`, `failed`, `error`, `cancelling`, `cancelled`, `skipped`
  - `error` (string, optional)
    The error that occurred
  - `failures_count` (integer, required, format: int32)
    The number of times the operation failed
  - `retry_at` (string, optional, format: date-time)
    A timestamp indicating when the operation was last retried
  - `created_at` (string, required, format: date-time)
    A timestamp indicating when the operation was created
  - `updated_at` (string, required, format: date-time)
    A timestamp indicating when the operation status was last updated
  - `total_duration_ms` (integer, required, format: int32)
    The total duration of the operation in milliseconds

### Code examples

```bash
curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/snapshots/$SNAPSHOT_ID/restore" \
  -X POST \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```typescript
import { createNeonClient, raw } from '@neon/sdk';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY });
const { data } = await raw.restoreSnapshot({
  client: neon.client,
  path: {
    project_id: process.env.PROJECT_ID,
    snapshot_id: process.env.SNAPSHOT_ID
  }
});
```

### Console

Console path: Projects → Backup & restore

### Errors

**default**
General Error.

The request may or may not be safe to retry, depending on the HTTP method, response status code,
and whether a response was received.

- If no response is returned from the API, a network error or timeout likely occurred.
- In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results.

The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**.
The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout.

Any request that returns a `503 Service Unavailable` response is always safe to retry.

Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Default: ``
- `message` (string, required)
  Error message