Skip to main content
Neon Postgres Docs

Search documentation

Type to search this documentation.

List branches

GET/projects/{project_id}/branchesList branches

Retrieves a list of branches for the specified project.

Each Neon project has a root branch named main. A branch_id value has a br- prefix. A project may contain child branches that were branched from main or from another branch. A parent branch is identified by the parent_id value, which is the id of the parent branch. For related information, see Manage branches.

Parameters

project_idstringpathrequired

The Neon project ID

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

searchstringquery

Search by branch `name` or `id`. You can specify partial `name` or `id` values to filter results.

sort_bystringquery

Sort the branches by sort_field. If not provided, branches will be sorted by updated_at descending order

one of "name", "created_at", "updated_at"

one of "name", "created_at", "updated_at" · default "updated_at"

cursorstringquery

A cursor to use in pagination. A cursor defines your place in the data list. Include `response.pagination.next` in subsequent API calls to fetch next page of the list.

sort_orderstringquery

Defines the sorting order of entities.

one of "asc", "desc"

one of "asc", "desc" · default "desc"

limitintegerquery

The maximum number of records to be returned in the response

maximum 10000 · minimum 1

include_deletedbooleanquery

If true, return recoverable deleted branches too (soft-deleted within the recovery window). If false or not provided, return only active (non-deleted) branches. This parameter is part of the Branch Recovery feature, which is in preview and not available to all users.

default false

Responses

200Returned a list of branches for the specified projectapplication/json
value
allOf · 3 options
Option 1objectBranchesResponse
branchesarray of objectrequired

Branches in the project. Each includes `id`, `name`, `current_state`, and `created_at`.

Show child attributes
Show array items
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

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.

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 2objectAnnotationsMapResponse
annotationsobjectrequired

Map of annotations keyed by resource identifier, where each value contains the annotation data for that resource.

Option 3objectCursorPaginationResponse
paginationobject

To paginate the response, issue an initial request with `limit` value. Then, add the value returned in the response `.pagination.next` attribute into the request under the `cursor` query parameter to the subsequent request to retrieve next page in pagination. The contents on cursor `next` are opaque, clients are not expected to make any assumptions on the format of the data inside the cursor.

Show child attributes
nextstring

Cursor for the next page of results. Pass it as the `cursor` query parameter on the next request. Absent on the last page.

sort_bystring

Field by which the results were sorted, echoing the request's sort_by parameter.

sort_orderstring

Sort order active for this page. Pass back as `sort_order` in the next request to maintain consistent ordering. Valid values are `asc` and `desc`.

Example response
{
  "annotations": {
    "br-aged-salad-637688": {
      "created_at": "2022-11-23T17:42:25Z",
      "object": {
        "id": "br-aged-salad-637688",
        "type": "console/branch"
      },
      "updated_at": "2022-11-23T17:42:26Z",
      "value": {
        "vercel-commit-ref": "test"
      }
    }
  },
  "branches": [
    {
      "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
    },
    {
      "active_time_seconds": 100,
      "compute_time_seconds": 100,
      "cpu_used_sec": 100,
      "created_at": "2022-11-30T19:09:48Z",
      "creation_source": "console",
      "current_state": "ready",
      "data_transfer_bytes": 1000000,
      "default": true,
      "id": "br-sweet-breeze-497520",
      "init_source": "parent-data",
      "logical_size": 28,
      "name": "dev2",
      "parent_id": "br-aged-salad-637688",
      "parent_lsn": "0/1DE2850",
      "project_id": "shiny-wind-028834",
      "protected": false,
      "state_changed_at": "2022-11-30T20:09:48Z",
      "updated_at": "2022-11-30T19:09:49Z",
      "written_data_bytes": 100800
    },
    {
      "active_time_seconds": 100,
      "compute_time_seconds": 100,
      "cpu_used_sec": 100,
      "created_at": "2022-11-30T17:36:57Z",
      "creation_source": "console",
      "current_state": "ready",
      "data_transfer_bytes": 1000000,
      "default": true,
      "id": "br-raspy-hill-832856",
      "init_source": "parent-data",
      "logical_size": 21,
      "name": "dev1",
      "parent_id": "br-aged-salad-637688",
      "parent_lsn": "0/19623D8",
      "project_id": "shiny-wind-028834",
      "protected": false,
      "state_changed_at": "2022-11-30T20:09:48Z",
      "updated_at": "2022-11-30T17:36:57Z",
      "written_data_bytes": 100800
    }
  ],
  "pagination": {
    "next": "eyJjcmVhdGV",
    "sort_by": "updated_at",
    "sort_order": "desc"
  }
}
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"
}
Documentation menu