[metadata]
description: Data resides in a branch. Each Neon project is created with a root branch, which is also designated as your default branch. Projects created in the Neon Console have a root branch named production, wh...
og:description: Data resides in a branch. Each Neon project is created with a root branch, which is also designated as your default branch. Projects created in the Neon Console have a root branch named production, wh...
og:image: https://neon.com/docs/og?title=TWFuYWdlIGJyYW5jaGVz&category=TWFuYWdlICYgb3BlcmF0ZQ==
og:site_name: Neon
og:title: Manage branches - Neon Docs
og:type: article
og:url: https://neon.com/docs/manage/branches
twitter:card: summary_large_image
twitter:description: Data resides in a branch. Each Neon project is created with a root branch, which is also designated as your default branch. Projects created in the Neon Console have a root branch named production, wh...
twitter:image: https://neon.com/docs/og?title=TWFuYWdlIGJyYW5jaGVz&category=TWFuYWdlICYgb3BlcmF0ZQ==
twitter:site: @neondatabase
twitter:title: Manage branches - Neon Docs
viewport: width=device-width, initial-scale=1, viewport-fit=cover

[canonical-links]
https://neon.com/docs/manage/branches

[document-links]
/docs
AI Gateway: /docs/ai-gateway/overview
AI agents on Neon: /docs/ai/ai-agents-tools
API keys: /docs/manage/api-keys
APIs & SDKs: /docs/reference/api
About: /about-us
Account recovery: /docs/manage/account-recovery
Accounts: /docs/manage/accounts
Active queries: /docs/introduction/monitor-active-queries
Add members by domain: /docs/manage/orgs-add-members-by-domain
Apache Software Foundation: https://www.apache.org
Auth: /docs/auth/overview
Automate pg_dump backups: /docs/manage/backup-pg-dump-automate
Backup & restore: /docs/guides/backup-restore
Backup & restore: /docs/manage/backups
Backup with pg_dump: /docs/manage/backup-pg-dump
Blog: /blog
Branch archiving: /docs/guides/branch-archiving
Branch expiration guide: /docs/guides/branch-expiration
Branches: /docs/manage/branches
Branching with the Neon CLI: /docs/cli/branches
Branching: /docs/introduction/branching
Building on Neon: /docs/guides/platform-integration-overview
CCPA Compliant: https://trust.neon.com/?itemUid=4064ac33-7b48-407b-aed7-ce02971d1ec1
CLI actions: /docs/manage/orgs-cli
California Privacy: https://www.databricks.com/legal/supplemental-privacy-notice-california-residents
Careers: https://www.databricks.com/company/careers/open-positions?department=engineering&location=all&itm_source=www&itm_category=company&itm_page=engineering-at-databricks&itm_location=body&itm_component=hero&itm_offer=open-positions
Changelog: /docs/changelog
Community Guides: /guides
Community: /docs/community/community-intro
Compliance Guide: /docs/security/hipaa
Computes: /docs/manage/computes
Contact Sales: /contact-sales
Create an API key: /docs/manage/api-keys#create-an-api-key
Create branch: /docs/reference/api/branches/create-project-branch
Data API: /docs/data-api/overview
Data anonymization: /docs/workflows/data-anonymization
Database access: /docs/manage/database-access
Databases: /docs/manage/databases
Datadog: /docs/guides/datadog
Delete branches: /docs/reference/api/branches/delete-project-branch
Discord Server: https://discord.gg/92vNTzKDGp
Discord: https://discord.gg/92vNTzKDGp
Docs: /docs
Edit on GitHub: https://github.com/neondatabase/website/tree/main/content/docs/manage/branches.md
Examples repo: https://github.com/neondatabase/examples
FAQs: /faqs
Frameworks: /docs/get-started/frameworks
GDPR Compliant: https://trust.neon.com/?itemUid=45220873-6e51-4dbb-b1b1-37d66ee9ef95
Get started: /docs/introduction
GitHub: https://github.com/neondatabase/neon
Glossary: /docs/reference/glossary
Grafana Cloud: /docs/guides/grafana-cloud
HIPAA Compliant: /docs/security/hipaa
History window: /docs/introduction/history-window
ISO 27001 Certified: https://trust.neon.com/?itemUid=1fed9faa-4a87-427c-9a95-96b4d6bf66b7
ISO 27701 Certified: https://trust.neon.com/?itemUid=dc79cbc7-c99d-4eb9-891e-f5dc44b943d7
Instant restore: /docs/guides/branch-restore
Instant restore: /docs/introduction/branch-restore
Integrations & tooling: /docs/guides/integrations
Integrations: /docs/manage/integrations
Languages: /docs/get-started/languages
Learn PostgreSQL: https://neon.com/postgresql/tutorial
LinkedIn: https://www.linkedin.com/company/neon-inc/
List branches: /docs/reference/api/branches/list-project-branches
Log in: https://console.neon.tech/login
Logs: /docs/introduction/monitor-logs
Manage & operate: /docs/manage/platform
Manage API Keys: /docs/manage/api-keys
Manage Organizations: /docs/manage/orgs-manage
Manage computes: /docs/manage/computes#view-a-compute
Manage databases: /docs/manage/databases
Manage organizations via API: /docs/manage/orgs-api
Manage roles: /docs/manage/roles
Metrics & logs: /docs/reference/metrics-logs
Modern Slavery Statement: https://www.databricks.com/legal/modern-slavery-policy-statement
Monitoring dashboard: /docs/introduction/monitoring-page
Multitenancy: /docs/guides/multitenancy
Neon API Reference: /docs/reference/api
Neon API Reference: /docs/reference/api/branches/create-project-branch
Neon API Reference: /docs/reference/api/branches/delete-project-branch
Neon API Reference: /docs/reference/api/branches/list-project-branches
Neon API: /docs/reference/api
Neon CLI commands — branches: /docs/cli/branches
Neon CLI: /docs/cli
Neon Functions: /docs/compute/functions/overview
Neon Platform Terms: /platform-terms
Neon SQL Editor: /docs/get-started/query-with-neon-sql-editor
Neon status loading...: https://neonstatus.com/
Neon-Managed Vercel integration: /docs/guides/neon-managed-vercel-integration
Neon: /
Neon’s Sub Contractors: /hipaa-contractors
Next Computes: /docs/manage/computes
Object Storage: /docs/storage/overview
Object hierarchy: /docs/manage/overview
OpenTelemetry: /docs/guides/opentelemetry
Organizations: /docs/manage/organizations
Overview: /docs/introduction/monitoring
Overview: /docs/manage/backups
Overview: /docs/manage/maintenance-updates-overview
Overview: /docs/manage/organizations
Part 1 - Create an S3 bucket: /docs/manage/backups-aws-s3-backup-part-1
Part 2 - Automate nightly backups: /docs/manage/backups-aws-s3-backup-part-2
Permissions quickstart: /docs/manage/project-permissions-get-started
PgHero: /docs/introduction/monitor-pghero
Plans & billing: /docs/introduction/about-billing
Platform maintenance: /docs/manage/platform-maintenance
PostgreSQL Tutorial: /postgresql/tutorial
Postgres: /docs/postgres/overview
Previous Multitenancy: /docs/guides/multitenancy
Privacy Notice: https://www.databricks.com/legal/privacynotice
Production checklist: /docs/get-started/production-checklist
Project collaboration: /docs/guides/project-collaboration-guide
Projects: /docs/manage/projects
Protected branches guide: /docs/guides/protected-branches
Query organization metrics via API: /docs/manage/orgs-api-consumption
Query performance: /docs/introduction/monitor-query-performance
Query with Neon's SQL Editor: /docs/get-started/query-with-neon-sql-editor
RSS feeds: /docs/reference/feeds
Regions: /docs/introduction/regions
Reset from parent: /docs/guides/reset-from-parent
Resilience & architecture: /docs/introduction/architecture-overview
Roadmap: /docs/introduction/roadmap
Roles: /docs/manage/roles
SOC 2 Certified: https://trust.neon.com/?itemUid=7bfa66da-33ab-49de-8391-e329738a1ae9
Schema-only branches: /docs/guides/branching-schema-only
Security & compliance: /docs/security/security-overview
Security: /security
Sign up: https://console.neon.tech/signup
Startups: /startups
Status: /docs/introduction/status
Support: /docs/introduction/support
System operations: /docs/manage/operations
Tables: /docs/guides/tables
Terms of Use: https://www.databricks.com/legal/terms-of-use
Transfer projects: /docs/manage/orgs-project-transfer
Trust Center: https://trust.neon.com
Updates: /docs/manage/updates
User permissions: /docs/manage/user-permissions
X.com: https://twitter.com/neondatabase/
You can now deploy Neon Functions - they live in the branch next to your DB, are long-running, perfect for agents and realtime: https://neon.com/blog/neon-functions-backend-logic-next-to-your-data
YouTube: https://www.youtube.com/channel/UCoMzQTJSIr7-RU1QbomQI2w
archived: /docs/guides/branch-archiving
branch protection: /docs/guides/protected-branches
create branch API call: /docs/reference/api/branches/create-project-branch
history window: /docs/introduction/history-window
https://discord.gg/92vNTzKDGp
https://github.com/neondatabase/neon
https://neon.com/docs/llms.txt: https://neon.com/docs/llms.txt
jq: https://stedolan.github.io/jq/
pgAdmin: /docs/introduction/monitor-pgadmin
plan allowances: /docs/introduction/plans
request a storage increase in the feedback form in console: https://console.neon.tech/app/settings?modal=feedback&modalparams=%22Storage%20limit%20increase%22
reset: /docs/manage/branches#reset-a-branch-from-parent

[structured-data]
{"@context":"https://schema.org","@type":"Article","author":{"@type":"Organization","name":"Neon"},"headline":"Manage branches"}

[content]
Manage branches - Neon Docs
You can now deploy Neon Functions - they live in the branch next to your DB, are long-running, perfect for agents and realtime
Neon
Docs
Search
...
⌘K
Ask AI
Log in
Sign up
Get started
Products
Postgres
Auth
Data API
Neon Functions
Object Storage
AI Gateway
Platform
Manage & operate
Resilience & architecture
Security & compliance
Plans & billing
Building on Neon
AI agents on Neon
Reference
APIs & SDKs
Integrations & tooling
Glossary
Resources
Support & Community
Support
Community
Product updates
Status
Changelog
Roadmap
RSS feeds
Starter code
Examples repo
Learn PostgreSQL
Search
...
⌘K
Ask AI
Full Neon documentation index:
https://neon.com/docs/llms.txt
Manage & operate
Access & collaboration
Accounts
Permissions quickstart
User permissions
Organizations
Overview
Manage Organizations
Add members by domain
Transfer projects
Organizations API
Manage organizations via API
Query organization metrics via API
CLI
CLI actions
Project collaboration
Database access
API keys
Account recovery
Projects & resources
Object hierarchy
Projects
Multitenancy
Branches
Computes
Roles
Databases
Tables
Integrations
Monitoring & observability
Overview
Metrics & logs
Monitoring dashboard
System operations
Active queries
Query performance
Logs
Third-party monitoring
Datadog
Grafana Cloud
OpenTelemetry
pgAdmin
PgHero
Operations & maintenance
Production checklist
Backup & restore
Backup & restore
History window
Instant restore
Overview
Backup with pg_dump
Automate pg_dump backups
Part 1 - Create an S3 bucket
Part 2 - Automate nightly backups
Updates
Overview
Platform maintenance
Updates
Regions
/
Manage & operate
/
Branches
Manage branches
Copy page
Data resides in a branch. Each Neon project is created with a
root branch
, which is also designated as your
default branch
. Projects created in the Neon Console have a root branch named
production
, while projects created via the API or CLI have a root branch named
main
. You can create child branches from your root branch or from previously created branches. A branch can contain multiple databases and roles. Neon's
plan allowances
define the number of branches you can create.
A child branch is a copy-on-write clone of the parent branch. You can modify the data in a branch without affecting the data in the parent branch. For more information about branches and how you can use them in your development workflows, see
Branching
.
You can create and manage branches using the Neon Console,
Neon CLI
, or
Neon API
.
important
When working with branches, it is important to remove old and unused branches. Branches hold a lock on the data they contain, which will add to your storage usage as they age out of your project's
history window
.
Branch naming requirements
Specifying a branch name is optional. If you don't provide one, the branch name defaults to the automatically generated branch ID with a
br-
prefix (for example,
br-curly-wave-af4i4oeu
).
If you do specify a custom branch name when creating or renaming a branch, it must meet the following requirements:
Maximum length
: 256 characters (API limit). Note that the Neon Console enforces a more restrictive limit of 128 characters.
Uniqueness
: Branch names must be unique within a project. You cannot have two branches with the same name in the same project.
Non-empty
: Branch names cannot be empty or consist only of whitespace characters.
Character flexibility
: Unlike some other Neon resources (such as databases or roles), branch names have no special character restrictions. You can use any characters as long as they meet the requirements above.
Create a branch
To create a branch:
In the Neon Console, select a project.
Select
Branches
.
Click
New branch
to open the branch creation dialog.
Select a
Parent branch
. This determines the origin of the schema and data for your new branch. By default, your project's default branch (named
main
if the project was created with the CLI or API, or
production
if created in the Console) is selected, but you can choose any existing branch in your project.
Specify a branch name, or leave it blank to use the default generated name.
Select what to include in the new branch:
Current data
: Creates a copy of the parent branch’s latest data and schema, resulting in an isolated database that reflects the parent at the time of creation.
Past data
: Creates a copy using data from a specific past date and time of the parent branch. The parent branch must have the relevant history.
note
You can only specify a date and time that falls within your
history window
.
Schema only
: Replicates only the database schema (tables, views, roles, etc.) from the parent branch, without copying any of the actual data. This is useful for testing migrations or building new test data without exposing sensitive real-world data. See
Schema-only branches
.
Anonymized data
: Creates a branch with masked sensitive data. You can configure data anonymization rules to protect personally identifiable information while preserving realistic data sets for development. See
Data anonymization
.
Configure auto-deletion: By default,
Automatically delete branch after
is checked with 1 day selected to help prevent unused branches from accumulating. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable expiration entirely. This is useful for CI/CD pipelines and short-lived development environments. Note: This default only applies when creating branches through the Console; API and CLI branches have no expiration by default. Refer to our
Branch expiration guide
for details.
Click
Create
to create your branch.
You are presented with the connection details for your new branch and directed to the
Branch
overview page where you are shown the details for your new branch.
Postgres role passwords on branches
When creating a new branch, the branch will have the same Postgres roles and passwords as the parent branch. If you want your branch created with new role passwords, you can enable
branch protection
.
View branches
To view the branches in a Neon project:
In the Neon Console, select a project.
Select
Branches
to view all current branches in the project.
Branch details in this table view include:
Branch
: The branch name, which is a generated name if no name was specified when created.
Parent
: Indicates the parent from which this branch was created, helping you track your branch hierarchy.
Compute hours
: Number of hours the branch's compute was active so far in the current billing period.
Primary compute
: Shows the current compute size and status for the branch's compute.
Data size
: Indicates the logical data size of the branch, helping you monitor your plan's storage limit. Data size does not include history.
Created by
: The account or integration that created the branch.
Last active
: Shows when the branch's compute was last active.
Select a branch from the table to view details about the branch.
Branch details shown on the branch page may include:
Archive status
: This only appears if the branch was archived. For more, see
Branch archiving
.
ID
: The branch ID. Branch IDs have a
br-
prefix.
Created on
: The date and time the branch was created.
Compute hours
: The compute hours used by the default branch in the current billing period.
Data size
: The logical data size of the branch. Data size does not include history.
Parent branch
: The branch from which this branch was created (only applicable to child branches).
The branch details page also includes details about the
Computes
,
Roles & Databases
, and
Child branches
that belong to the branch. All of these objects are associated with a particular branch. For information about these objects, see:
Manage computes
.
Manage roles
Manage databases
View branches
Branch archiving
On the Free plan, Neon automatically archives inactive branches to cost-efficient archive storage after a defined threshold. For more, see
Branch archiving
.
note
For branches with predictable lifespans, you can set an expiration date when creating branches to automatically delete them at a specified time. This offers an alternative to archiving for temporary development and testing environments, ensuring cleanup happens exactly when needed.
Rename a branch
Neon permits renaming a branch, including your project's default branch. To rename a branch:
In the Neon Console, select a project.
Select
Branches
to view the branches for the project.
Select a branch from the table.
On the branch overview page, click the
More
drop-down menu and select
Rename
.
Specify a new name for the branch and click
Save
.
Set a branch as default
Each Neon project is created with a default branch (named
main
if the project was created with the CLI or API, or
production
if created in the Console), but you can designate any branch as your project's default branch. When creating a new branch without specifying the parent, a new branch is created from your project's default branch. Default branch is automatically selected in the UI when creating the new branch, and it's used in the
create branch API call
. The
Neon-Managed Vercel integration
also creates preview deployment branches from your project's default branch.
For more information, see
Default branch
.
To set a branch as the default branch:
In the Neon Console, select a project.
Select
Branches
to view the branches for the project.
Select a branch from the table.
On the branch overview page, click the
More
drop-down menu and select
Set as default
.
In the
Set as default
confirmation dialog, click
Set as default
to confirm your selection.
Set a branch as protected
This feature is available on all Neon's paid plans, which supports up to five protected branches.
To set a branch as protected:
In the Neon Console, select a project.
Select
Branches
to view the branches for the project.
Select a branch from the table.
On the branch overview page, click the
More
drop-down menu and select
Set as protected
.
In the
Set as protected
confirmation dialog, click
Set as protected
to confirm your selection.
For details and configuration instructions, refer to our
Protected branches guide
.
Set a branch expiration
To set or update a branch's expiration (auto-deletion TTL):
In the Neon Console, select a project.
Select
Branches
to view the branches for the project.
Select a branch from the table.
On the branch overview page, click the
Actions
drop-down menu and select
Edit expiration
.
Set a new expiration date and time, or toggle off "Automatically delete branch after" to remove expiration.
Click
Save
.
For details and configuration instructions, refer to our
Branch expiration guide
.
Connect to a branch
Connecting to a database in a branch requires connecting via a compute associated with the branch. The following steps describe how to connect using
psql
and a connection string obtained from the Neon Console.
tip
You can also query the databases in a branch from the Neon SQL Editor. For instructions, see
Query with Neon's SQL Editor
.
In the Neon Console, select a project.
Find the connection string for your database by clicking the
Connect
button on your
Project Dashboard
. Select the branch, the database, and the role you want to connect with.
Copy the connection string. A connection string includes your role name, the compute hostname, and database name.
Connect with
psql
as shown below.
psql
postgresql://[user]:[password]@[neon_hostname]/[dbname]
tip
A compute hostname starts with an
ep-
prefix. You can also find a compute hostname on the
Branches
page in the Neon Console. See
View branches
.
If you want to connect from an application, the
Connect to your database modal
, accessed by clicking
Connect
on the project
Dashboard
, and the
Frameworks
and
Languages
sections in the documentation provide various connection examples.
Reset a branch from parent
You can use Neon's
Reset from parent
feature to instantly update a branch with the latest schema and data from its parent. This feature can be an integral part of your CI/CD automation.
You can use the Neon Console, CLI, or API. For details, see
Reset from parent
.
Restore a branch to its own or another branch's history
There are several restore operations available using Neon's instant restore feature:
Restore a branch to its own history
Restore a branch to the head of another branch
Restore a branch to the history of another branch
You can use the Neon Console, CLI, or API. For more details, see
Instant restore
.
Delete a branch
Deleting a branch is a permanent action. Deleting a branch also deletes the databases and roles that belong to the branch as well as the compute associated with the branch. You cannot delete a branch that has child branches. The child branches must be deleted first.
To delete a branch:
In the Neon Console, select a project.
Select
Branches
.
Select a branch from the table.
On the branch overview page, click the
More
drop-down menu and select
Delete
.
On the confirmation dialog, click
Delete
.
tip
For temporary branches, consider setting an expiration date when creating them to automate cleanup and reduce manual deletion overhead.
Check the data size
You can check the logical data size for the databases on a branch by viewing the
Data size
value on the
Branches
page or page in the Neon Console. Alternatively, you can run the following query on your branch from the
Neon SQL Editor
or any SQL client connected to your database:
SELECT
pg_size_pretty(
sum
(pg_database_size(datname)))
FROM
pg_database;
The query value may differ slightly from the
Data size
reported in the Neon Console.
Data size is your logical data size.
note
Paid plans support a logical data size of up to
16 TB per branch
. When a branch reaches this limit, write performance drops, but you can still drop or delete data to reclaim space. To increase this limit,
request a storage increase in the feedback form in console
.
Branch types
Neon has different branch types with different characteristics.
Root branch
A root branch is a branch without a parent branch. Each Neon project starts with a root branch (named
production
in the Console,
main
via API/CLI), which cannot be deleted and is set as the
default branch
for the project.
Neon also supports two other types of root branches that have no parent but
can
be deleted:
Backup branches
, created by instant restore operations on other root branches.
Schema-only branches
.
The number of root branches allowed in a project depends on your Neon plan.
Plan
Root branch allowance per project
Free
3
Launch
5
Scale
25
Default branch
Each Neon project has a default branch. In the Neon Console, your default branch is identified by a
DEFAULT
tag. You can designate any branch as the default branch for your project.
When creating a new branch without specifying the parent, a new branch is created from your project's default branch. The
Neon-Managed Vercel integration
also creates preview deployment branches from your project's default branch.
Non-default branch
Any branch not designated as the default branch is considered a non-default branch. You can rename or delete non-default branches.
Protected branch
Neon's protected branches feature implements a series of protections:
Protected branches cannot be deleted.
Protected branches cannot be
reset
.
Projects with protected branches cannot be deleted.
Computes associated with a protected branch cannot be deleted.
New passwords are automatically generated for Postgres roles on branches created from protected branches.
See below
.
With additional configuration steps, you can apply IP Allow restrictions to protected branches only. See
below
.
Protected branches are not
archived
due to inactivity.
Typically, a protected status is given to a branch or branches that hold production data or sensitive data. The protected branch feature is only supported on Neon's paid plans. See
Set a branch as protected
.
Schema-only branch
A branch that replicates only the database schema from a source branch, without copying any of the actual data. This feature is particularly valuable when working with sensitive information. Rather than creating branches that include confidential data, you can duplicate just the database structure and then populate it with your own data.
Schema-only branches are
root branches
, meaning they have no parent. As a root branch, each schema-only branch starts an independent line of data in a Neon project.
See
Schema-only branches
.
Backup branch
A branch created by an
instant restore
operation. When you restore a branch from a particular point in time, the current branch is saved as a backup branch. Performing a restore operation on a root branch, creates a backup branch without a parent branch (a root branch). See
Instant restore
.
Branch with expiration
A branch with an expiration timestamp is automatically deleted when the expiration time is reached. Any branch can have an expiration timestamp added or removed at any time. Use it for temporary development and testing environments.
Branching with the Neon CLI
The Neon CLI supports creating and managing branches. For instructions, see
Neon CLI commands — branches
. For a Neon CLI branching guide, see
Branching with the Neon CLI
.
Branching with the Neon API
Branch actions performed in the Neon Console can also be performed using the Neon API. The following examples demonstrate how to create, view, and delete branches using the Neon API. For other branch-related API methods, refer to the
Neon API Reference
.
note
The API examples that follow may not show all of the user-configurable request body attributes that are available to you. To view all of the attributes for a particular method, refer to the method's request body schema in the
Neon API Reference
.
The
jq
option specified in each example is an optional third-party tool that formats the
JSON
response, making it easier to read. For information about this utility, see
jq
.
Prerequisites
A Neon API request requires an API key. For information about obtaining an API key, see
Create an API key
. In the examples shown below,
$NEON_API_KEY
is specified in place of an actual API key, which you must provide when making a Neon API request.
note
To learn more about the types of API keys you can create — personal, organization, or project-scoped — see
Manage API Keys
.
Create a branch with the API
The following Neon API method creates a branch. To view the API documentation for this method, refer to the
Neon API Reference
.
POST
/projects/{project_id}/branches
The API method appears as follows when specified in a cURL command. The
endpoints
attribute creates a compute, which is required to connect to the branch. A branch can be created with or without a compute. The
branch
attribute specifies the parent branch.
note
This method does not require a request body. Without a request body, the method creates a branch from the project's default branch, and a compute is not created.
curl
'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches'
\
-H
'Accept: application/json'
\
-H
"Authorization: Bearer $NEON_API_KEY"
\
-H
'Content-Type: application/json'
\
-d
'{
"endpoints": [
{
"type": "read_write"
}
],
"branch": {
"parent_id": "br-wispy-dew-591433"
}
}'
|
jq
The
project_id
for a Neon project is found on the
Settings
page in the Neon Console, or you can find it by listing the projects for your Neon account using the Neon API.
The
parent_id
can be obtained by listing the branches for your project. See
List branches
. The
<parent_id>
is the
id
of the branch you are branching from. A branch
id
has a
br-
prefix. You can branch from your Neon project's default branch or a previously created branch.
The response body includes information about the branch, the branch's compute, and the
create_branch
and
start_compute
operations that were initiated.
Response body
For attribute definitions, find the
Create branch
endpoint in the
Neon API Reference
. Definitions are provided in the
Responses
section.
{
"branch"
:
{
"id"
:
"br-curly-wave-af4i4oeu"
,
"project_id"
:
"dry-heart-13671059"
,
"parent_id"
:
"br-morning-meadow-afu2s1jl"
,
"parent_lsn"
:
"0/1FA22C0"
,
"name"
:
"br-curly-wave-af4i4oeu"
,
"current_state"
:
"init"
,
"pending_state"
:
"ready"
,
"state_changed_at"
:
"2025-08-04T07:13:09Z"
,
"creation_source"
:
"console"
,
"primary"
:
false
,
"default"
:
false
,
"protected"
:
false
,
"cpu_used_sec"
:
0
,
"compute_time_seconds"
:
0
,
"active_time_seconds"
:
0
,
"written_data_bytes"
:
0
,
"data_transfer_bytes"
:
0
,
"created_at"
:
"2025-08-04T07:13:09Z"
,
"updated_at"
:
"2025-08-04T07:13:09Z"
,
"created_by"
:
{
"name"
:
"your@email.com"
,
"image"
:
""
}
,
"init_source"
:
"parent-data"
}
,
"endpoints"
:
[
{
"host"
:
"ep-cool-darkness-123456.c-2.us-west-2.aws.neon.tech"
,
"id"
:
"ep-cool-darkness-123456"
,
"project_id"
:
"dry-heart-13671059"
,
"branch_id"
:
"br-curly-wave-af4i4oeu"
,
"autoscaling_limit_min_cu"
:
0.25
,
"autoscaling_limit_max_cu"
:
0.25
,
"region_id"
:
"aws-us-west-2"
,
"type"
:
"read_write"
,
"current_state"
:
"init"
,
"pending_state"
:
"active"
,
"settings"
:
{}
,
"pooler_enabled"
:
false
,
"pooler_mode"
:
"transaction"
,
"disabled"
:
false
,
"passwordless_access"
:
true
,
"creation_source"
:
"console"
,
"created_at"
:
"2025-08-04T07:13:09Z"
,
"updated_at"
:
"2025-08-04T07:13:09Z"
,
"proxy_host"
:
"c-2.us-west-2.aws.neon.tech"
,
"suspend_timeout_seconds"
:
0
,
"provisioner"
:
"k8s-neonvm"
}
]
,
"operations"
:
[
{
"id"
:
"8289b00a-4341-48d2-b3f1-d0c8dbb7e806"
,
"project_id"
:
"dry-heart-13671059"
,
"branch_id"
:
"br-curly-wave-af4i4oeu"
,
"action"
:
"create_branch"
,
"status"
:
"running"
,
"failures_count"
:
0
,
"created_at"
:
"2025-08-04T07:13:09Z"
,
"updated_at"
:
"2025-08-04T07:13:09Z"
,
"total_duration_ms"
:
0
}
,
{
"id"
:
"a3c9baa4-6732-4774-a141-9d03396babce"
,
"project_id"
:
"dry-heart-13671059"
,
"branch_id"
:
"br-curly-wave-af4i4oeu"
,
"endpoint_id"
:
"ep-cool-darkness-123456"
,
"action"
:
"start_compute"
,
"status"
:
"scheduling"
,
"failures_count"
:
0
,
"created_at"
:
"2025-08-04T07:13:09Z"
,
"updated_at"
:
"2025-08-04T07:13:09Z"
,
"total_duration_ms"
:
0
}
]
,
"roles"
:
[
{
"branch_id"
:
"br-curly-wave-af4i4oeu"
,
"name"
:
"alex"
,
"protected"
:
false
,
"created_at"
:
"2025-08-04T07:07:55Z"
,
"updated_at"
:
"2025-08-04T07:07:55Z"
}
]
,
"databases"
:
[
{
"id"
:
2886327
,
"branch_id"
:
"br-curly-wave-af4i4oeu"
,
"name"
:
"dbname"
,
"owner_name"
:
"alex"
,
"created_at"
:
"2025-08-04T07:07:55Z"
,
"updated_at"
:
"2025-08-04T07:07:55Z"
}
]
,
"connection_uris"
:
[
{
"connection_uri"
:
"postgresql://alex:AbC123dEf@ep-cool-darkness-123456.c-2.us-west-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require"
,
"connection_parameters"
:
{
"database"
:
"dbname"
,
"password"
:
"AbC123dEf"
,
"role"
:
"alex"
,
"host"
:
"ep-cool-darkness-123456.c-2.us-west-2.aws.neon.tech"
,
"pooler_host"
:
"ep-cool-darkness-123456-pooler.c-2.us-west-2.aws.neon.tech"
}
}
]
}
List branches with the API
The following Neon API method lists branches for the specified project. To view the API documentation for this method, refer to the
Neon API Reference
.
GET
/projects/{project_id}/branches
The API method appears as follows when specified in a cURL command:
curl
'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches'
\
-H
'accept: application/json'
\
-H
"Authorization: Bearer $NEON_API_KEY"
|
jq
The
project_id
for a Neon project is found on the
Settings
page in the Neon Console, or you can find it by listing the projects for your Neon account using the Neon API.
The response body lists the project's default branch and any child branches. The name of the default branch in this example is
main
.
Response body
For attribute definitions, find the
List branches
endpoint in the
Neon API Reference
. Definitions are provided in the
Responses
section.
{
"branches"
:
[
{
"id"
:
"br-curly-wave-af4i4oeu"
,
"project_id"
:
"dry-heart-13671059"
,
"parent_id"
:
"br-morning-meadow-afu2s1jl"
,
"parent_lsn"
:
"0/1FA22C0"
,
"parent_timestamp"
:
"2025-08-04T07:08:48Z"
,
"name"
:
"br-curly-wave-af4i4oeu"
,
"current_state"
:
"ready"
,
"state_changed_at"
:
"2025-08-04T07:13:09Z"
,
"creation_source"
:
"console"
,
"primary"
:
false
,
"default"
:
false
,
"protected"
:
false
,
"cpu_used_sec"
:
0
,
"compute_time_seconds"
:
0
,
"active_time_seconds"
:
0
,
"written_data_bytes"
:
0
,
"data_transfer_bytes"
:
0
,
"created_at"
:
"2025-08-04T07:13:09Z"
,
"updated_at"
:
"2025-08-04T07:18:15Z"
,
"created_by"
:
{
"name"
:
"your@email.com"
,
"image"
:
""
}
,
"init_source"
:
"parent-data"
}
,
{
"id"
:
"br-morning-meadow-afu2s1jl"
,
"project_id"
:
"dry-heart-13671059"
,
"name"
:
"main"
,
"current_state"
:
"ready"
,
"state_changed_at"
:
"2025-08-04T07:07:58Z"
,
"logical_size"
:
30777344
,
"creation_source"
:
"console"
,
"primary"
:
true
,
"default"
:
true
,
"protected"
:
false
,
"cpu_used_sec"
:
0
,
"compute_time_seconds"
:
0
,
"active_time_seconds"
:
0
,
"written_data_bytes"
:
0
,
"data_transfer_bytes"
:
0
,
"created_at"
:
"2025-08-04T07:07:55Z"
,
"updated_at"
:
"2025-08-04T07:13:11Z"
,
"created_by"
:
{
"name"
:
"your@email.com"
,
"image"
:
""
}
,
"init_source"
:
"parent-data"
}
]
,
"annotations"
:
{}
,
"pagination"
:
{
"sort_by"
:
"updated_at"
,
"sort_order"
:
"DESC"
}
}
Delete a branch with the API
The following Neon API method deletes the specified branch. To view the API documentation for this method, refer to the
Neon API Reference
.
DELETE
/projects/{project_id}/branches/{branch_id}
The API method appears as follows when specified in a cURL command:
curl
-X
'DELETE'
\
'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-curly-wave-af4i4oeu'
\
-H
'accept: application/json'
\
-H
"Authorization: Bearer $NEON_API_KEY"
|
jq
The
project_id
for a Neon project is found on the
Settings
page in the Neon Console, or you can find it by listing the projects for your Neon account using the Neon API.
The
branch_id
can be found by listing the branches for your project. The
<branch_id>
is the
id
of a branch. A branch
id
has a
br-
prefix. See
List branches
.
The response body shows information about the branch being deleted and the
suspend_compute
and
delete_timeline
operations that were initiated.
Response body
For attribute definitions, find the
Delete branches
endpoint in the
Neon API Reference
. Definitions are provided in the
Responses
section.
{
"branch"
:
{
"id"
:
"br-curly-wave-af4i4oeu"
,
"project_id"
:
"dry-heart-13671059"
,
"parent_id"
:
"br-morning-meadow-afu2s1jl"
,
"parent_lsn"
:
"0/1FA22C0"
,
"parent_timestamp"
:
"2025-08-04T07:08:48Z"
,
"name"
:
"br-curly-wave-af4i4oeu"
,
"current_state"
:
"ready"
,
"pending_state"
:
"storage_deleted"
,
"state_changed_at"
:
"2025-08-04T07:13:09Z"
,
"logical_size"
:
30851072
,
"creation_source"
:
"console"
,
"primary"
:
false
,
"default"
:
false
,
"protected"
:
false
,
"cpu_used_sec"
:
0
,
"compute_time_seconds"
:
0
,
"active_time_seconds"
:
0
,
"written_data_bytes"
:
0
,
"data_transfer_bytes"
:
0
,
"created_at"
:
"2025-08-04T07:13:09Z"
,
"updated_at"
:
"2025-08-04T07:21:55Z"
,
"created_by"
:
{
"name"
:
"your@email.com"
,
"image"
:
""
}
,
"init_source"
:
"parent-data"
}
,
"operations"
:
[
{
"id"
:
"eb85073d-53fc-4d37-a32a-ca9e9ea1eeb1"
,
"project_id"
:
"dry-heart-13671059"
,
"branch_id"
:
"br-curly-wave-af4i4oeu"
,
"endpoint_id"
:
"ep-soft-art-af5jvg5j"
,
"action"
:
"suspend_compute"
,
"status"
:
"running"
,
"failures_count"
:
0
,
"created_at"
:
"2025-08-04T07:21:55Z"
,
"updated_at"
:
"2025-08-04T07:21:55Z"
,
"total_duration_ms"
:
0
}
,
{
"id"
:
"586af342-1ffe-4e0a-9e11-326db1164ad7"
,
"project_id"
:
"dry-heart-13671059"
,
"branch_id"
:
"br-curly-wave-af4i4oeu"
,
"action"
:
"delete_timeline"
,
"status"
:
"scheduling"
,
"failures_count"
:
0
,
"created_at"
:
"2025-08-04T07:21:55Z"
,
"updated_at"
:
"2025-08-04T07:21:55Z"
,
"total_duration_ms"
:
0
}
]
}
You can verify that a branch is deleted by listing the branches for your project. See
List branches
. The deleted branch should no longer be listed.
Need help?
Join our
Discord Server
to ask questions or see what others are doing with Neon. For paid plan support options, see
Support
.
Was this page helpful?
Yes
No
Thank you for your feedback!
Edit on GitHub
Previous
Multitenancy
Next
Computes
On this page
Branch naming requirements
Create a branch
View branches
Branch archiving
Rename a branch
Set a branch as default
Set a branch as protected
Set a branch expiration
Connect to a branch
Reset a branch from parent
Restore a branch to its own or another branch's history
Delete a branch
Check the data size
Branch types
Branching with the Neon CLI
Branching with the Neon API
Need help?
Set up Neon with AI
Copy neon init command
Neon Docs
Neon
Neon is part of the Databricks Platform
Neon status loading...
© Neon 2026. All rights reserved. Apache, Apache Spark, Spark, the Spark Logo, Apache Iceberg, Iceberg, and the Apache Iceberg logo are trademarks of the
Apache Software Foundation
.
Privacy Notice
Terms of Use
Neon Platform Terms
Modern Slavery Statement
California Privacy
Company
About
Blog
Careers
Contact Sales
Security
Resources
Docs
Changelog
Support
Community Guides
FAQs
PostgreSQL Tutorial
Startups
Community
Discord
GitHub
X.com
LinkedIn
YouTube
Compliance
CCPA
Compliant
GDPR
Compliant
ISO 27001
Certified
ISO 27701
Certified
SOC 2
Certified
HIPAA
Compliant
Compliance Guide
Neon’s Sub Contractors
Trust Center
