---
title: "Get branch details"
method: GET
path: "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}"
tags: ["Branches"]
---

# Get branch details

`GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID}`

## Request

- Base URL: `https://api.xata.tech`
- URL: `https://api.xata.tech/organizations/{organizationID}/projects/{projectID}/branches/{branchID}`
- Auth: OAuth 2
  - Implicit: `https://auth.xata.io/realms/xata/protocol/openid-connect/auth`
  - Scopes: `branch:read`

Retrieves detailed information about a specific branch by its ID, including status, connection string, and configuration.

## Path parameters

- `organizationID` string, required
- `projectID` string, required
- `branchID` string, required

## Response `200`

Branch details retrieved successfully

- BranchMetadata: Detailed metadata about a branch, including its status and configuration
  - `id` string, required: Unique identifier for the branch
  - `name` string, required: Human-readable name of the branch
  - `description` string: Optional description of the branch purpose or contents
  - `createdAt` string, date-time, required: Timestamp when the branch was created
  - `updatedAt` string, date-time, required: Timestamp when the branch was last updated
  - `parentID` string, nullable: Identifier of the parent branch if this is a derived branch, null otherwise
  - `region` string, required: Geographic region where the branch is deployed
  - `status` BranchStatus, required: Detailed status information about a branch and its underlying database cluster
    - `status` string, required: Status indicator for the branch according to CNPG
    - `statusType` 'STATUS_TYPE_UNSPECIFIED' | 'STATUS_TYPE_HEALTHY' | 'STATUS_TYPE_TRANSIENT' | 'STATUS_TYPE_FAULT' | 'STATUS_TYPE_HIBERNATED', required: Type of status of the branch
    - `message` string: Human-readable message explaining the current status
    - `lifecycle` ClusterLifecycle: Information about the current lifecycle state of a database cluster
      - `state` 'ready' | 'creating' | 'updating' | 'upgrading' | 'unknown', required: Current operational state of the cluster (ready, creating, updating, etc.)
      - `reason` string: Reason for the current lifecycle state, especially useful for non-ready states
      - `phase` string, required: Current phase within the lifecycle process
    - `instanceCount` integer, required: Total number of database instances in the cluster
    - `instanceReadyCount` integer, required: Number of database instances that are ready and operational
    - `instances` InstanceStatus[], required: Details about each individual database instance in the cluster
      - `id` string, required: Unique identifier for the database instance
      - `status` string, required: Current operational status of the instance
      - `primary` boolean, required: Indicates if this instance is currently the primary (write) instance
      - `targetPrimary` boolean, required: Indicates if this instance is the target primary during a failover operation
  - `connectionString` string, nullable, required: Deprecated: retrieve the connection string from the branch credentials endpoint (GET .../branches/{branchID}/credentials) instead. The hostname in this connection string carries a -deprecated marker in its first DNS label.
  - `publicAccess` boolean, required: Whether the branch allows public access without authentication
  - `backupsEnabled` boolean, required: Whether the branch is in a region that supports backups
  - `scaleToZero` ScaleToZeroConfiguration, required: Configuration for scaling branches to zero when not in use
    - `enabled` boolean, required: Whether scale to zero is enabled
    - `inactivityPeriodMinutes` integer, required: Duration in minutes after which branches will be hibernated if not accessed
  - `configuration` ClusterConfiguration, required: Configuration details for a database cluster backing a branch
    - `region` string, required: Geographic region where the cluster will be deployed
    - `storage` integer: Branch storage in GiB (gigabytes)
    - `instanceType` string, required: The instance type according to the xata instance types available
    - `image` string, required: PostgreSQL image to use for the database instances
    - `replicas` integer, required: Number of replicas in the branch. Every child branch is created with no replicas. This can be updated.
    - `postgresConfigurationParameters` object: Arbitrary PostgreSQL configuration parameters for the cluster
    - `preloadLibraries` string[]: List of PostgreSQL extensions and libraries to preload
  - `backupConfiguration` BackupConfiguration: Details about the branch continuous backup configuration
    - `retentionPeriod` integer: Number of days of point-in-time recovery to guarantee. You can restore the branch to any point within this many days. To provide this, the most recent full backup taken before the start of the window is always kept, along with all changes made after it. Because of this, restore points older than retentionPeriod are sometimes available, but how far back they go depends on the backup schedule and is not guaranteed.
    - `backupTime` string: When to take a full backup, in UTC, in the format D:HH:MM. D is * for every day, or 0-6 for one day of the week (0 is Sunday). If it is not set, a random time on Sunday between 02:00 and 05:59 is used.

## Other responses

- `400`: Generic error response for most error conditions
- `401`: Error response when authentication or authorization fails
- `404`: Generic error response for most error conditions
- `5XX`: Unexpected Error
- `default`: Unexpected Error

## Changes

- **2026-07-27** `16f6200eae92`: 1 info
  - response property `connectionString` deprecated

[Operation history](https://skmtc.dev/xataio/apis/xata-api/changes/organizations/:organizationID/projects/:projectID/branches/:branchID/get.md)

---

[API](https://skmtc.dev/xataio/apis/xata-api.md) - [All operations](https://skmtc.dev/xataio/apis/xata-api/llms.txt) - [OpenAPI document](https://skmtc.dev/xataio/apis/xata-api/revisions/4bc5ad58a6c6?raw)