Branch expiration

Branch expiration allows you to set automatic deletion timestamps on branches. When a branch reaches its expiration time, it is automatically deleted.

• When and why to use branch expiration
• How to set expiration timestamps via Console, CLI, and API
• How expiration timestamps and TTL intervals work
• Restrictions and best practices

• Branching with the Neon CLI
• Branching with the Neon API
• Manage branches
• Branching workflows

Branch expiration is ideal for temporary branches that have predictable lifespans:

• CI/CD environments - Test branches that should clean up after pipeline completion
• Feature development - Time-boxed feature branches with known deadlines
• Automated testing - Ephemeral test environments created by scripts
• AI workflows - Temporary environments managed without human intervention

Without automatic expiration, these branches accumulate over time, increasing storage costs and project clutter.

Branch expiration uses a time-to-live (TTL) model. When you set an expiration on a branch, you're defining how long the branch should exist before automatic deletion.

When you set an expiration timestamp on a branch:

1. The system stores both:

   • Expiration timestamp (expires_at) - The scheduled date and time when the branch will be deleted
   • TTL interval (ttl_interval_seconds) - The duration between creation/update and expiration (for example, 24 hours = 86400 seconds), a read-only value

2. A background process monitors branches and deletes them after their expiration time is reached

3. If you reset a branch from its parent, the TTL countdown restarts using the original interval

You can set, update, or remove expiration timestamps through three interfaces:

• Console - When creating a branch, Automatically delete branch after is checked by default with 1 day selected. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable. When updating an existing branch, you can select a custom date and time.
• CLI - Use the --expires-at flag when creating or updating a branch with RFC 3339 format. Note: Expiration must be explicitly set; there is no default.
• API - Use the expires_at parameter with RFC 3339 format. Note: Expiration must be explicitly set; there is no default.

See the Examples section below for detailed usage of each method.

The expires_at parameter must use RFC 3339 format with second-level precision:

Format patterns:

YYYY-MM-DDTHH:MM:SSZ         (UTC)
YYYY-MM-DDTHH:MM:SS+HH:MM    (Positive UTC offset)
YYYY-MM-DDTHH:MM:SS-HH:MM    (Negative UTC offset)

Valid examples:

• 2025-07-15T18:02:16Z (UTC)
• 2025-07-15T18:02:16-05:00 (Eastern Standard Time)
• 2025-07-15T18:02:16+09:00 (Japan Standard Time)

Requirements:

• Time zone is required: use either Z for UTC or a numeric offset like +05:00
• Fractional seconds are optional but only second precision is stored
• Timestamp must be in the future
• Maximum expiration is 30 days from the current time

To maintain system integrity, expiration timestamps cannot be added to:

• Protected branches - Cannot expire protected branches or protect branches with expiration
• Default branches - Cannot expire default branches or set expiring branches as default
• Parent branches - Cannot expire branches that have children or create children from expiring branches

Branch expiration is not supported with these Neon features:

• Data API

Branch expiration is supported with Managed Better Auth.

• Console
• CLI
• API

1. Navigate to the Branches page in the Console
2. Click New branch
3. Enter branch name and select parent branch
4. By default, Automatically delete branch after is checked with 1 day selected. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable.

5. Click Create

# Create branch expiring at specific date/timeneon branches create \  --project-id <project-id> \  --name feature-test \  --parent development \  --expires-at "2026-01-29T18:02:16Z"# Create branch expiring in 2 hours (using dynamic date)# Linux/GNU: $(date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ)# macOS/BSD: $(date -u -v+2H +%Y-%m-%dT%H:%M:%SZ)neon branches create \  --project-id <project-id> \  --name ci-test \  --parent development \  --expires-at "$(date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ)"

# Create branch that expires in 24 hourscurl --request POST \     --url https://console.neon.tech/api/v2/projects/{project_id}/branches \     --header 'Accept: application/json' \     --header "Authorization: Bearer $NEON_API_KEY" \     --header 'Content-Type: application/json' \     --data '{       "branch": {         "name": "feature-test",         "parent_id": "br-main-12345",         "expires_at": "2026-01-29T18:02:16Z"       }     }'# Example response{  "branch": {    "id": "br-feature-67890",    "name": "feature-test",    "parent_id": "br-main-12345",    "expires_at": "2026-01-29T18:02:16Z",    "ttl_interval_seconds": 86400,    "created_at": "2026-01-28T18:02:16Z"  }}

• Console
• CLI
• API

1. Navigate to the Branches page in the Console
2. Choose the Update expiration option for your branch

3. To update: Select a new date and time
4. To remove: Uncheck Automatically delete branch after
5. Click Save

# Update expiration to new timestampneon branches set-expiration \  <branch-id> \  --expires-at "2026-01-29T12:00:00Z" \  --project-id <project-id># Extend expiration by 7 days from now# Linux/GNU: $(date -u -d '+7 days' +%Y-%m-%dT%H:%M:%SZ)# macOS/BSD: $(date -u -v+7d +%Y-%m-%dT%H:%M:%SZ)neon branches set-expiration \  <branch-id> \  --expires-at "$(date -u -d '+7 days' +%Y-%m-%dT%H:%M:%SZ)" \  --project-id <project-id># Remove expiration from a branchneon branches set-expiration \  <branch-id> \  --expires-at null \  --project-id <project-id>

# Update branch expiration to specific datecurl --request PATCH \     --url https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id} \     --header 'Accept: application/json' \     --header "Authorization: Bearer $NEON_API_KEY" \     --header 'Content-Type: application/json' \     --data '{       "branch": {         "expires_at": "2026-01-29T12:00:00Z"       }     }'# Remove expiration from a branchcurl --request PATCH \     --url https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id} \     --header 'Accept: application/json' \     --header "Authorization: Bearer $NEON_API_KEY" \     --header 'Content-Type: application/json' \     --data '{       "branch": {         "expires_at": null       }     }'

Check expiration status of your branches:

• Console
• CLI
• API

1. Navigate to the Branches page in the Console
2. Click on the desired branch to open the Branch Overview
3. See information similar to the following if branch expiration is set:

neon branches get <branch_id> --project-id <project_id>

curl --request GET \
     --url https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id} \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY"

POST /projects/{project_id}/branches

• expires_at (optional) - Timestamp for automatic deletion in RFC 3339 format

PATCH /projects/{project_id}/branches/{branch_id}

• expires_at (optional, nullable) - Update or remove expiration

  • Timestamp value: Sets/updates expiration
  • null: Removes expiration
  • Omitted: No change

Branches with expiration include two key fields:

• expires_at - The scheduled deletion timestamp (RFC 3339 format)
• ttl_interval_seconds - The original TTL duration in seconds (read-only)

When you create a branch with a TTL of 24 hours, ttl_interval_seconds is set to 86400 (seconds). The expires_at value is calculated as creation time plus 24 hours.

If you reset the branch from its parent, the expires_at value is recalculated using the preserved ttl_interval_seconds value, starting from the reset time. The interval itself remains unchanged.

Example response:

{
  "branch": {
    "id": "br-feature-67890",
    "expires_at": "2026-01-29T18:02:16Z",
    "ttl_interval_seconds": 86400,
    "created_at": "2026-01-28T18:02:16Z"
  }
}

In this example, the branch will be deleted 24 hours after creation.

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.