Delete branch | Neon Postgres Docs

DELETE/projects/{project_id}/branches/{branch_id}Delete branch

Deletes the specified branch from a project and places all compute endpoints into an idle state, breaking existing client connections.

The deletion completes after all operations finish. You cannot delete a project's root or default branch, or a branch that has a child branch. A project must have at least one branch.

For related information, see Manage branches.

Parameters

project_idstringpathrequired

The Neon project ID

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

branch_idstringpathrequired

The branch ID

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

Responses

valueBranchOperations

allOf · 2 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 2objectOperationsResponse

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": 100,
    "compute_time_seconds": 100,
    "cpu_used_sec": 100,
    "created_at": "2022-11-23T17:42:25Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 1000000,
    "default": true,
    "id": "br-aged-salad-637688",
    "init_source": "parent-data",
    "logical_size": 28,
    "name": "main",
    "project_id": "shiny-wind-028834",
    "protected": false,
    "state_changed_at": "2022-11-30T20:09:48Z",
    "updated_at": "2022-11-23T17:42:26Z",
    "written_data_bytes": 100800
  },
  "operations": [
    {
      "action": "suspend_compute",
      "branch_id": "br-sweet-breeze-497520",
      "created_at": "2022-12-01T19:53:05Z",
      "endpoint_id": "ep-soft-violet-752733",
      "failures_count": 0,
      "id": "b6afbc21-2990-4a76-980b-b57d8c2948f2",
      "project_id": "shiny-wind-028834",
      "status": "running",
      "total_duration_ms": 100,
      "updated_at": "2022-12-01T19:53:05Z"
    },
    {
      "action": "delete_timeline",
      "branch_id": "br-sweet-breeze-497520",
      "created_at": "2022-12-01T19:53:05Z",
      "failures_count": 0,
      "id": "b6afbc21-2990-4a76-980b-b57d8c2948f2",
      "project_id": "shiny-wind-028834",
      "status": "scheduling",
      "total_duration_ms": 100,
      "updated_at": "2022-12-01T19:53:05Z"
    }
  ]
}

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

branch_idrequiredpath parameter

curl -X DELETE 'https://console.neon.tech/api/v2/projects/string/branches/string'

const response = await fetch('https://console.neon.tech/api/v2/projects/string/branches/string', { method: 'DELETE' });
const data = await response.json();

const response = await fetch('https://console.neon.tech/api/v2/projects/string/branches/string', { method: 'DELETE' });
console.log(await response.json());

import requests

response = requests.request("DELETE", "https://console.neon.tech/api/v2/projects/string/branches/string")
print(response.json())

package main

import (
	"context"
	"net/http"
)

func main() {
	ctx := context.Background()
	req, err := http.NewRequestWithContext(ctx, "DELETE", "https://console.neon.tech/api/v2/projects/string/branches/string", nil)
	if err != nil {
		panic(err)
	}
	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/branches/string");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "DELETE");
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://console.neon.tech/api/v2/projects/string/branches/string"))
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://console.neon.tech/api/v2/projects/string/branches/string")
request = Net::HTTPGenericRequest.new("DELETE", false, true, uri)
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.Delete, "https://console.neon.tech/api/v2/projects/string/branches/string");
using var response = await client.SendAsync(request);

{
  "branch": {
    "active_time_seconds": 100,
    "compute_time_seconds": 100,
    "cpu_used_sec": 100,
    "created_at": "2022-11-23T17:42:25Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 1000000,
    "default": true,
    "id": "br-aged-salad-637688",
    "init_source": "parent-data",
    "logical_size": 28,
    "name": "main",
    "project_id": "shiny-wind-028834",
    "protected": false,
    "state_changed_at": "2022-11-30T20:09:48Z",
    "updated_at": "2022-11-23T17:42:26Z",
    "written_data_bytes": 100800
  },
  "operations": [
    {
      "action": "suspend_compute",
      "branch_id": "br-sweet-breeze-497520",
      "created_at": "2022-12-01T19:53:05Z",
      "endpoint_id": "ep-soft-violet-752733",
      "failures_count": 0,
      "id": "b6afbc21-2990-4a76-980b-b57d8c2948f2",
      "project_id": "shiny-wind-028834",
      "status": "running",
      "total_duration_ms": 100,
      "updated_at": "2022-12-01T19:53:05Z"
    },
    {
      "action": "delete_timeline",
      "branch_id": "br-sweet-breeze-497520",
      "created_at": "2022-12-01T19:53:05Z",
      "failures_count": 0,
      "id": "b6afbc21-2990-4a76-980b-b57d8c2948f2",
      "project_id": "shiny-wind-028834",
      "status": "scheduling",
      "total_duration_ms": 100,
      "updated_at": "2022-12-01T19:53:05Z"
    }
  ]
}

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