Restore snapshot | Neon Postgres Docs

POST/projects/{project_id}/snapshots/{snapshot_id}/restoreRestore snapshot

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

Parameters

project_idstringpathrequired

The Neon project ID

pattern ^[a-z0-9-]{1,60}$

snapshot_idstringpathrequired

The snapshot ID

pattern ^[a-z0-9-]{1,60}$

namestringquery

Deprecated. Use the `name` field in the request body instead. Removal scheduled for November 29, 2025. A name for the newly restored branch. If omitted, a default name will be generated.

Request body

application/json

object

finalize_restoreboolean

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

namestring

A name for the newly restored branch. If not provided, the server generates a unique name for the branch automatically.

target_branch_idstring

ID of the branch to restore the snapshot into. Defaults to the snapshot's source branch (`snapshot.source_branch_id`); fails if that cannot be determined.

Example request

{
  "finalize_restore": false,
  "name": "string",
  "target_branch_id": "string"
}

Responses

value

allOf · 3 options

Option 1objectBranchResponse

branchobjectrequired

Show child attributes

active_time_secondsinteger · int64required

Total time this branch's compute has been active during the current billing period, in seconds (not weighted by compute size). Distinct from `compute_time_seconds`, which is CU-weighted.

compute_time_secondsinteger · int64required

Total Postgres compute time consumed by this branch during the current billing period, in CU-seconds (weighted by compute size). Divide by 3600 for CU-hours.

cpu_used_secinteger · int64required

Deprecated. Use `compute_time_seconds` instead. 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.

created_atstring · date-timerequired

A timestamp indicating when the branch was created

created_byobject

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.

Show child attributes

imagestring

The URL to the user's avatar image.

namestring

Display name of the user who created the branch.

creation_sourcestringrequired

The branch creation source

current_statestringrequired

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 Postgres storage. Expect slow query response times.

data_transfer_bytesinteger · int64required

Total data transferred out of the branch, in bytes. Used as a consumption metric.

defaultbooleanrequired

Whether the branch is the project's default branch

expires_atstring · 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.

idstringrequired

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`.

pattern ^[a-z0-9-]{1,60}$

init_sourcestring

Source of initialization for the branch. `parent-data` (default) copies schema and data from the parent. `parent-schema` copies schema only from the parent. `schema-only` creates a root branch with schema only. `import` initializes from an external import.

last_reset_atstring · date-time

A timestamp indicating when the branch was last reset

logical_sizeinteger · int64

The logical size of the branch, in bytes

namestringrequired

The branch name

parent_idstring

The `branch_id` of the parent branch

pattern ^[a-z0-9-]{1,60}$

parent_lsnstring

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_timestampstring · 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.

pending_statestring

primaryboolean

Deprecated. Use the `default` field. Whether the branch is the project's primary branch.

project_idstringrequired

The ID of the project this branch belongs to.

pattern ^[a-z0-9-]{1,60}$

protectedbooleanrequired

Whether the branch is protected. Protected branches (and their computes) cannot be deleted, archived, or reset, and block deletion of the project.

recoveryobject

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.

Show child attributes

deleted_atstring · date-timerequired

Timestamp when the branch was deleted

deletion_methodstringrequired

How the branch was deleted: 'user' for manual deletion, 'ttl' for TTL expiration

one of "user", "ttl"

recoverable_untilstring · date-timerequired

Timestamp when the recovery window expires and the branch will be permanently deleted

restore_statusstring

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_asstring

ID of the target branch which was replaced when this branch was restored

restored_fromstring

ID of the snapshot that was the restore source for this branch

restricted_actionsarray of object

A list of actions that are currently restricted for this branch and the reason why.

Show child attributes

Show array items

An action that is currently restricted for the branch and the reason why.

namestringrequired

The name of a restricted action on a branch. `restore`: the branch cannot be used as a restore target. `delete-rw-endpoint`: the read-write endpoint for the branch cannot be deleted.

reasonstringrequired

A human-readable explanation of why the action is restricted.

state_changed_atstring · date-timerequired

A UTC timestamp indicating when the `current_state` began

ttl_interval_secondsinteger

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.

updated_atstring · date-timerequired

A timestamp indicating when the branch was last updated

written_data_bytesinteger · int64required

Data written by this branch during the current billing period, in bytes.

Option 2objectEndpointsOptionalResponse

endpointsarray of object

Compute endpoints associated with the project.

Show child attributes

Show array items

autoscaling_limit_max_cunumberrequired

minimum 0.25

autoscaling_limit_min_cunumberrequired

minimum 0.25

branch_idstringrequired

The ID of the branch this compute endpoint belongs to.

pattern ^[a-z0-9-]{1,60}$

compute_release_versionstring

Attached compute's release version number.

created_atstring · date-timerequired

A timestamp indicating when the compute endpoint was created

creation_sourcestringrequired

The compute endpoint creation source

current_statestringrequired

Lifecycle state of the compute endpoint. `init`: being initialized. `active`: running and accepting connections. `idle`: suspended (scaled to zero).

one of "init", "active", "idle"

disabledbooleanrequired

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.

hoststringrequired

The hostname of the compute endpoint. This is the hostname specified when connecting to a Neon database.

idstringrequired

The compute endpoint ID. Compute endpoint IDs have an `ep-` prefix. For example: `ep-little-smoke-851426`

pattern ^[a-z0-9-]{1,60}$

last_activestring · date-time

A timestamp indicating when the compute endpoint was last active

namestring

Optional name of the compute endpoint

passwordless_accessbooleanrequired

Whether to permit passwordless access to the compute endpoint

pending_statestring

Lifecycle state of the compute endpoint. `init`: being initialized. `active`: running and accepting connections. `idle`: suspended (scaled to zero).

one of "init", "active", "idle"

pooler_enabledbooleanrequired

Deprecated. To use connection pooling, append `-pooler` to the endpoint ID in the connection string.

pooler_modestringrequired

Deprecated. The connection pooler mode. Neon supports PgBouncer in `transaction` mode only. Removal scheduled for June 20, 2026.

one of "transaction"

project_idstringrequired

The ID of the project this compute endpoint belongs to.

pattern ^[a-z0-9-]{1,60}$

provisionerstringrequired

proxy_hoststringrequired

Deprecated. Use the `host` property instead.

region_idstringrequired

Cloud region where the resource's Postgres compute and storage reside (for example, `aws-us-east-1`). Valid values are returned by `GET /regions`.

settingsobjectrequired

A collection of settings for a compute endpoint

Show child attributes

pg_settingsobject

A raw representation of Postgres settings

pgbouncer_settingsobject

Deprecated. A raw representation of PgBouncer settings. Removal scheduled for June 20, 2026.

preload_librariesobject

The shared libraries to preload into the project's compute instances.

Show child attributes

enabled_librariesarray of string

Names of shared preload libraries to enable for the project.

Show child attributes

use_defaultsboolean

When true, the project's preload libraries include the platform default set in addition to any libraries listed in `enabled_libraries`.

started_atstring · date-time

A timestamp indicating when the compute endpoint was last started

suspend_timeout_secondsinteger · int64required

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).

maximum 604800 · minimum -1

suspended_atstring · date-time

A timestamp indicating when the compute endpoint was last suspended

typestringrequired

Compute endpoint type. `read_write`: the primary read-write endpoint (one per branch). `read_only`: a read replica endpoint (multiple allowed per branch).

one of "read_only", "read_write"

updated_atstring · date-timerequired

A timestamp indicating when the compute endpoint was last updated

Option 3objectOperationsResponse

operationsarray of objectrequired

Show child attributes

Show array items

An asynchronous action Neon performs on your resources (for example, starting a compute or creating a branch). Fields such as `action`, `status`, and `total_duration_ms` describe the operation and its progress.

actionstringrequired

The action performed by the operation

one of "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"

branch_idstring

The ID of the branch this operation ran on.

pattern ^[a-z0-9-]{1,60}$

created_atstring · date-timerequired

A timestamp indicating when the operation was created

endpoint_idstring

The ID of the compute endpoint this operation ran on.

pattern ^[a-z0-9-]{1,60}$

errorstring

Human-readable message describing why the operation failed.

failures_countinteger · int32required

The number of times the operation failed

idstring · uuidrequired

The operation ID

project_idstringrequired

The ID of the project this operation ran on.

pattern ^[a-z0-9-]{1,60}$

retry_atstring · date-time

A timestamp indicating when the operation was last retried

statusstringrequired

Lifecycle state of the operation. `scheduling`: queued, not yet started. `running`: actively executing. `finished`: completed successfully. `failed`: ended with a failure. `error`: ended with a terminal error. `cancelling`: cancellation requested but not yet complete. `cancelled`: stopped before completion. `skipped`: bypassed without executing.

one of "scheduling", "running", "finished", "failed", "error", "cancelling", "cancelled", "skipped"

total_duration_msinteger · int32required

The total duration of the operation in milliseconds

updated_atstring · date-timerequired

A timestamp indicating when the operation status was last updated

Example response

{
  "branch": {
    "active_time_seconds": 922200,
    "compute_time_seconds": 823880990,
    "cpu_used_sec": 461100,
    "created_at": "2022-11-30T19:09:48Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 72911987,
    "default": true,
    "id": "br-wispy-meadow-118737",
    "init_source": "parent-data",
    "name": "dev2",
    "parent_id": "br-aged-salad-637688",
    "parent_lsn": "0/1DE2850",
    "project_id": "spring-example-302709",
    "protected": false,
    "state_changed_at": "2022-11-30T20:09:48Z",
    "updated_at": "2022-12-01T19:53:05Z",
    "written_data_bytes": 542998300
  },
  "endpoints": [
    {
      "autoscaling_limit_max_cu": 1,
      "autoscaling_limit_min_cu": 1,
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-12-03T15:37:07Z",
      "creation_source": "console",
      "current_state": "init",
      "disabled": false,
      "host": "ep-silent-smoke-806639.us-east-2.aws.neon.tech",
      "id": "ep-silent-smoke-806639",
      "name": "My cool compute",
      "passwordless_access": true,
      "pending_state": "active",
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "project_id": "spring-example-302709",
      "provisioner": "k8s-neonvm",
      "proxy_host": "us-east-2.aws.neon.tech",
      "region_id": "aws-us-east-2",
      "settings": {
        "pg_settings": {}
      },
      "suspend_timeout_seconds": 0,
      "type": "read_write",
      "updated_at": "2022-12-03T15:37:07Z"
    }
  ],
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-11-15T20:02:00Z",
      "endpoint_id": "ep-silent-smoke-806639",
      "failures_count": 0,
      "id": "d8ac46eb-a757-42b1-9907-f78322ee394e",
      "project_id": "spring-example-302709",
      "status": "finished",
      "total_duration_ms": 200,
      "updated_at": "2022-11-15T20:02:02Z"
    }
  ]
}

defaultGeneral 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. application/json

objectGeneralError

codestringrequired

default ""

messagestringrequired

Error message

request_idstring

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.

Example response

{
  "code": "",
  "message": "string",
  "request_id": "string"
}

Examples

project_idrequiredpath parameter

snapshot_idrequiredpath parameter

namequery parameter

curl -X POST 'https://console.neon.tech/api/v2/projects/string/snapshots/string/restore?name=string' \
  -H 'Content-Type: application/json' \
  -d '{"finalize_restore":false,"name":"string","target_branch_id":"string"}'

const response = await fetch('https://console.neon.tech/api/v2/projects/string/snapshots/string/restore?name=string', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"finalize_restore":false,"name":"string","target_branch_id":"string"}),
});
const data = await response.json();

const response = await fetch('https://console.neon.tech/api/v2/projects/string/snapshots/string/restore?name=string', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"finalize_restore\":false,\"name\":\"string\",\"target_branch_id\":\"string\"}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://console.neon.tech/api/v2/projects/string/snapshots/string/restore?name=string",
    headers={"Content-Type": "application/json"},
    data='{"finalize_restore":false,"name":"string","target_branch_id":"string"}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"finalize_restore":false,"name":"string","target_branch_id":"string"}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://console.neon.tech/api/v2/projects/string/snapshots/string/restore?name=string", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://console.neon.tech/api/v2/projects/string/snapshots/string/restore?name=string");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"finalize_restore\":false,\"name\":\"string\",\"target_branch_id\":\"string\"}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://console.neon.tech/api/v2/projects/string/snapshots/string/restore?name=string"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"finalize_restore\":false,\"name\":\"string\",\"target_branch_id\":\"string\"}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://console.neon.tech/api/v2/projects/string/snapshots/string/restore?name=string")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"finalize_restore\":false,\"name\":\"string\",\"target_branch_id\":\"string\"}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://console.neon.tech/api/v2/projects/string/snapshots/string/restore?name=string");
request.Content = new StringContent("{\"finalize_restore\":false,\"name\":\"string\",\"target_branch_id\":\"string\"}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "branch": {
    "active_time_seconds": 922200,
    "compute_time_seconds": 823880990,
    "cpu_used_sec": 461100,
    "created_at": "2022-11-30T19:09:48Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 72911987,
    "default": true,
    "id": "br-wispy-meadow-118737",
    "init_source": "parent-data",
    "name": "dev2",
    "parent_id": "br-aged-salad-637688",
    "parent_lsn": "0/1DE2850",
    "project_id": "spring-example-302709",
    "protected": false,
    "state_changed_at": "2022-11-30T20:09:48Z",
    "updated_at": "2022-12-01T19:53:05Z",
    "written_data_bytes": 542998300
  },
  "endpoints": [
    {
      "autoscaling_limit_max_cu": 1,
      "autoscaling_limit_min_cu": 1,
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-12-03T15:37:07Z",
      "creation_source": "console",
      "current_state": "init",
      "disabled": false,
      "host": "ep-silent-smoke-806639.us-east-2.aws.neon.tech",
      "id": "ep-silent-smoke-806639",
      "name": "My cool compute",
      "passwordless_access": true,
      "pending_state": "active",
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "project_id": "spring-example-302709",
      "provisioner": "k8s-neonvm",
      "proxy_host": "us-east-2.aws.neon.tech",
      "region_id": "aws-us-east-2",
      "settings": {
        "pg_settings": {}
      },
      "suspend_timeout_seconds": 0,
      "type": "read_write",
      "updated_at": "2022-12-03T15:37:07Z"
    }
  ],
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-11-15T20:02:00Z",
      "endpoint_id": "ep-silent-smoke-806639",
      "failures_count": 0,
      "id": "d8ac46eb-a757-42b1-9907-f78322ee394e",
      "project_id": "spring-example-302709",
      "status": "finished",
      "total_duration_ms": 200,
      "updated_at": "2022-11-15T20:02:02Z"
    }
  ]
}

{
  "code": "",
  "message": "string",
  "request_id": "string"
}