Skip to main content
Neon Postgres Docs

Search documentation

Type to search this documentation.

Create project

POST/projectsCreate project

Creates a Neon project within an organization. If using a personal API key, include the org_id parameter to specify which organization to create the project in. If using an org API key, org_id is automatically inferred from the key. Plan limits define how many projects you can create. For more information, see Manage projects.

You can specify a region and Postgres version in the request body. Neon supports Postgres 14 through 18, with 19 rolling out to enabled regions. For supported regions and region_id values, see Regions.

Request body

required
application/json
objectProjectCreateRequest
projectobjectrequired

Configuration for the new project, including name, region, and Postgres compute and storage settings.

Show child attributes
autoscaling_limit_max_cunumber

minimum 0.25

autoscaling_limit_min_cunumber

minimum 0.25

branchobject

Configuration for the initial branch created with the project.

Show child attributes
annotationsobject

A free-form map of string key-value pairs for attaching metadata to a resource (for example, a git commit reference). Maximum 50 entries.

maxProperties 50

database_namestring

The database name. If not specified, the default database name, `neondb`, will be used.

namestring

The default branch name. If not specified, the default branch name, `main`, will be used.

maxLength 256 · minLength 1

role_namestring

The role name. If not specified, the default role name, `{database_name}_owner`, will be used.

default_endpoint_settingsobject

A collection of settings for a Neon endpoint

Show child attributes
autoscaling_limit_max_cunumber

minimum 0.25

autoscaling_limit_min_cunumber

minimum 0.25

pg_settingsobject

A raw representation of Postgres settings

pgbouncer_settingsobject

Deprecated. A raw representation of PgBouncer settings. Removal scheduled for June 20, 2026.

suspend_timeout_secondsinteger · int64

Duration of inactivity in seconds after which the compute endpoint is automatically suspended. The value `0` means use the default value. The value `-1` means never suspend. The default value is `300` seconds (5 minutes). The minimum value is `60` seconds (1 minute). The maximum value is `604800` seconds (1 week). For more information, see [Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).

maximum 604800 · minimum -1

history_retention_secondsinteger · int32

History window (point-in-time restore range) for all branches, in seconds. `0` disables it. Default 1 day (Free: 6 hours). Maximum depends on plan: Free 6 hours (21600), Launch 7 days (604800), Scale 30 days (2592000).

maximum 2592000 · minimum 0

namestring

The project name. If not specified, the name will be identical to the generated project ID

maxLength 256 · minLength 1

org_idstring

ID of the organization that will own the project. If omitted when using an organization API key, it is inferred from the key.

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

pg_versioninteger

The major Postgres version number. Supported versions are `14`, `15`, `16`, `17`, and `18`. `19` is rolling out and is accepted only in regions where it is enabled; requesting it elsewhere returns an error.

default 18 · maximum 19 · minimum 14

provisionerstring
region_idstring

The region identifier. Refer to our [Regions](https://neon.com/docs/introduction/regions) documentation for supported regions. Values are specified in this format: `aws-us-east-1`

settingsobject
Show child attributes
allowed_ipsobject

A list of IP addresses that are allowed to connect to the compute endpoint. If the list is empty or not set, all IP addresses are allowed. If protected_branches_only is true, the list will be applied only to protected branches.

Show child attributes
ipsarray of string

A list of IP addresses that are allowed to connect to the endpoint.

Show child attributes
protected_branches_onlyboolean

If true, the list will be applied only to protected branches.

audit_log_levelstring

one of "base", "extended", "full"

block_public_connectionsboolean

When set, connections from the public internet are disallowed. This supersedes the AllowedIPs list. This parameter is under active development and its semantics may change in the future.

block_vpc_connectionsboolean

When set, connections using VPC endpoints are disallowed. This parameter is under active development and its semantics may change in the future.

enable_logical_replicationboolean

Sets wal_level=logical for all compute endpoints in this project. All active endpoints will be suspended. Once enabled, logical replication cannot be disabled.

hipaaboolean

Enables HIPAA compliance mode for the project, including audit logging.

maintenance_windowobject

A maintenance window is a time period during which Neon may perform maintenance on the project's infrastructure. During this time, the project's compute endpoints may be unavailable and existing connections can be interrupted.

Show child attributes
end_timestringrequired

End time of the maintenance window, in the format of "HH:MM". Uses UTC.

start_timestringrequired

Start time of the maintenance window, in the format of "HH:MM". Uses UTC.

weekdaysarray of integerrequired

A list of weekdays when the maintenance window is active. Encoded as ints, where 1 - Monday, and 7 - Sunday.

Show child attributes
preload_librariesobject

The shared libraries to preload into the project's compute instances.

Show child attributes
enabled_librariesarray of string

Names of shared preload libraries to enable for the project.

Show child attributes
use_defaultsboolean

When true, the project's preload libraries include the platform default set in addition to any libraries listed in `enabled_libraries`.

quotaobject

Per-project consumption quotas. If a quota is exceeded, all active computes are automatically suspended and cannot be started via API calls or incoming connections. The exception is `logical_size_bytes`, which is enforced per branch. If a branch exceeds its `logical_size_bytes` quota, computes can still be started, but write operations will fail—allowing data to be deleted to free up space. Computes on other branches are not affected. Setting `logical_size_bytes` overrides any lower value set by the `neon.max_cluster_size` Postgres setting. Quotas are enforced using per-project consumption metrics with the same names. These metrics reset at the start of each billing period. `logical_size_bytes` is also an exception—it reflects the total data stored in a branch and does not reset. A zero or empty quota value means “unlimited.”

Show child attributes
active_time_secondsinteger · int64

The total amount of wall-clock time allowed to be spent by the project's compute endpoints.

minimum 0

compute_time_secondsinteger · int64

The total amount of CPU seconds allowed to be spent by the project's compute endpoints.

minimum 0

data_transfer_bytesinteger · int64

Total amount of data transferred from all of a project's branches using the proxy.

minimum 0

logical_size_bytesinteger · int64

Limit on the logical size of every project's branch. If a branch exceeds its `logical_size_bytes` quota, computes can still be started, but write operations will fail—allowing data to be deleted to free up space. Computes on other branches are not affected. Setting `logical_size_bytes` overrides any lower value set by the `neon.max_cluster_size` Postgres setting.

minimum 0

written_data_bytesinteger · int64

Total amount of data written to all of a project's branches.

minimum 0

store_passwordsboolean

Whether or not passwords are stored for roles in the Neon project. Storing passwords facilitates access to Neon features that require authorization.

Example request
{
  "project": {
    "name": "myproject",
    "pg_version": 15,
    "region_id": "aws-us-east-2"
  }
}

Responses

201Created a project. The project includes a connection URI with a database, password, and role. At least one non-protected role is created with a password. Wait until the operations are finished before attempting to connect to a project database. application/json
value
allOf · 7 options
Option 1objectProjectResponse
projectobjectrequired
Show child attributes
active_time_secondsinteger · int64required

Seconds. Control plane observed endpoints of this project being active this amount of wall-clock time. The value has some lag. The value is reset at the beginning of each billing period.

minimum 0

branch_logical_size_limitinteger · int64required

The logical size limit for a branch. The value is in MiB.

branch_logical_size_limit_bytesinteger · int64required

The logical size limit for a branch. The value is in B.

compute_last_active_atstring · date-time

The most recent time when any endpoint of this project was active. Omitted when observed no activity for endpoints of this project.

compute_time_secondsinteger · int64required

Seconds. The number of CPU seconds used by the project's compute endpoints, including compute endpoints that have been deleted. The value has some lag. The value is reset at the beginning of each billing period. Examples: 1. An endpoint that uses 1 CPU for 1 second is equal to `compute_time=1`. 2. An endpoint that uses 2 CPUs simultaneously for 1 second is equal to `compute_time=2`.

minimum 0

consumption_period_endstring · date-timerequired

A date-time indicating when Neon Cloud plans to stop measuring consumption for current consumption period.

consumption_period_startstring · date-timerequired

A date-time indicating when Neon Cloud started measuring consumption for current consumption period.

cpu_used_secinteger · int64required

Deprecated. Use `compute_time_seconds` instead.

created_atstring · date-timerequired

A timestamp indicating when the project was created

creation_sourcestringrequired

The project creation source

data_storage_bytes_hourinteger · int64required

Bytes-Hour. Project consumed that much Postgres storage hourly during the billing period. The value has some lag. The value is reset at the beginning of each billing period.

minimum 0

data_transfer_bytesinteger · int64required

Bytes. Egress traffic from the Neon cloud to the client for given project over the billing period. Includes deleted endpoints. The value has some lag. The value is reset at the beginning of each billing period.

minimum 0

default_endpoint_settingsobjectDefaultEndpointSettings ↑

A collection of settings for a Neon endpoint

effective_project_permissionvalue
Show child attributes
anyOf · 2 options
Option 1string
allOf · 1 option
Option 1stringProjectPermissionLevel

The caller's effective permission for a project when per-project permissions are enabled. `VIEWER` grants read access, `EDITOR` adds update access, and `ADMIN` grants full management. Omitted for personal projects, flag-off organizations, and non-user subjects.

one of "VIEWER", "EDITOR", "ADMIN"

Option 2nullnullable
hipaa_enabled_atstring · date-time

A timestamp indicating when HIPAA was enabled for this project

history_retention_secondsinteger · int32required

The number of seconds to retain the shared history for all branches in this project.

idstringrequired

The Neon project ID. Use as the `project_id` path parameter in other endpoints.

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

maintenance_scheduled_forstring · date-time

A timestamp indicating when project update begins. If set, computes might experience a brief restart around this time.

maintenance_starts_atstring · date-time

A timestamp indicating when project maintenance begins. If set, the project is placed into maintenance mode at this time.

namestringrequired

The project name

org_idstring

The Neon organization ID. Returned as `id` from `GET /users/me/organizations`.

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

ownerobject
Show child attributes
branches_limitintegerrequired

Maximum number of branches the owner is allowed to create across their projects.

emailstring · emailrequired

Email address of the project owner.

maxLength 256 · minLength 1

namestringrequired

Display name of the project owner.

subscription_typestringrequired

Type of subscription to Neon Cloud. Notice that for users without billing account this will be "UNKNOWN"

one of "UNKNOWN", "direct_sales", "direct_sales_v3", "aws_marketplace", "free_v2", "free_v3", "launch", "launch_v3", "scale", "scale_v3", "business", "vercel_pg_legacy"

owner_idstringrequired

ID of the organization that owns the project.

pg_versionintegerrequired

The major Postgres version number. Supported versions are `14`, `15`, `16`, `17`, and `18`. `19` is rolling out and is accepted only in regions where it is enabled; requesting it elsewhere returns an error.

default 18 · maximum 19 · minimum 14

platform_idstringrequired

The cloud platform identifier. Currently, only AWS is supported, for which the identifier is `aws`.

provisionerstringrequired
proxy_hoststringrequired

The proxy host for the project. This value combines the `region_id`, the `platform_id`, and the Neon domain (`neon.tech`).

quota_reset_atstring · date-time

Deprecated. Use the `consumption_period_end` field instead. A timestamp indicating when the project quota resets.

region_idstringrequired

Cloud region where the resource's Postgres compute and storage reside (for example, `aws-us-east-1`). Valid values are returned by `GET /regions`.

store_passwordsbooleanrequired

Whether or not passwords are stored for roles in the Neon project. Storing passwords facilitates access to Neon features that require authorization.

synthetic_storage_sizeinteger · int64

The current space occupied by the project in Postgres storage, in bytes. Synthetic Postgres storage size combines the logical data size and Write-Ahead Log (WAL) size for all branches in a project.

updated_atstring · date-timerequired

A timestamp indicating when the project was last updated

written_data_bytesinteger · int64required

Bytes. Amount of WAL that travelled through Postgres storage for given project across all branches. The value has some lag. The value is reset at the beginning of each billing period.

minimum 0

Option 2objectConnectionURIsResponse
connection_urisarray of objectrequired

Connection URIs for the project. Each entry contains credentials and should be treated as sensitive.

Show child attributes
Show array items
connection_parametersobjectrequired
Show child attributes
databasestringrequired

Name of the Postgres database used in the connection URI.

hoststringrequired

Hostname of the compute endpoint. Use `pooler_host` for the pooled connection hostname.

passwordstringrequired

Authentication password for the role, used in the connection URI.

pooler_hoststringrequired

PgBouncer (transaction mode) pooled host, the `-pooler` variant of `host`. Connect through it to work around the Postgres `max_connections` limit for serverless or connection-per-request workloads.

rolestringrequired

Postgres role used to authenticate the database connection.

connection_uristringrequired

The connection URI is defined as specified here: [Connection URIs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS) The connection URI can be used to connect to a Postgres database with psql or defined in a DATABASE_URL environment variable. When creating a branch from a parent with more than one role or database, the response body does not include a connection URI.

Option 3objectRolesResponse
rolesarray of objectrequired

Roles belonging to the branch. Each role includes fields such as `branch_id`, `name`, `protected`, `created_at`, and `updated_at`.

Show child attributes
Show array items
authentication_methodstring

Authentication method configured for this role: `password`, `oauth`, or `no_login`.

branch_idstringrequired

The ID of the branch this role belongs to.

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

created_atstring · date-timerequired

A timestamp indicating when the role was created

namestringrequired

Postgres role name within the branch.

passwordstring

The role password

protectedboolean

Whether or not the role is system-protected

updated_atstring · date-timerequired

A timestamp indicating when the role was last updated

Option 4objectDatabasesResponse
databasesarray of objectrequired

Databases on the branch. Each includes `id`, `name`, `owner_name`, and `created_at`.

Show child attributes
Show array items
branch_idstringrequired

The ID of the branch this database belongs to.

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

created_atstring · date-timerequired

A timestamp indicating when the database was created

idinteger · int64required

The database ID

namestringrequired

The database name

owner_namestringrequired

The name of role that owns the database

updated_atstring · date-timerequired

A timestamp indicating when the database was last updated

Option 5objectOperationsResponse
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

Option 6objectBranchResponse
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

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 7objectEndpointsResponse
endpointsarray of objectrequired

Compute endpoints in the project. Each includes `id`, `branch_id`, `host`, and `type`.

Show child attributes
Show array items
autoscaling_limit_max_cunumberrequired

minimum 0.25

autoscaling_limit_min_cunumberrequired

minimum 0.25

branch_idstringrequired

The ID of the branch this compute endpoint belongs to.

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

compute_release_versionstring

Attached compute's release version number.

created_atstring · date-timerequired

A timestamp indicating when the compute endpoint was created

creation_sourcestringrequired

The compute endpoint creation source

current_statestringrequired

Lifecycle state of the compute endpoint. `init`: being initialized. `active`: running and accepting connections. `idle`: suspended (scaled to zero).

one of "init", "active", "idle"

disabledbooleanrequired

Whether to restrict connections to the compute endpoint. Enabling this option schedules a suspend compute operation. A disabled compute endpoint cannot be enabled by a connection or console action.

hoststringrequired

The hostname of the compute endpoint. This is the hostname specified when connecting to a Neon database.

idstringrequired

The compute endpoint ID. Compute endpoint IDs have an `ep-` prefix. For example: `ep-little-smoke-851426`

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

last_activestring · date-time

A timestamp indicating when the compute endpoint was last active

namestring

Optional name of the compute endpoint

passwordless_accessbooleanrequired

Whether to permit passwordless access to the compute endpoint

pending_statestring

Lifecycle state of the compute endpoint. `init`: being initialized. `active`: running and accepting connections. `idle`: suspended (scaled to zero).

one of "init", "active", "idle"

pooler_enabledbooleanrequired

Deprecated. To use connection pooling, append `-pooler` to the endpoint ID in the connection string.

pooler_modestringrequired

Deprecated. The connection pooler mode. Neon supports PgBouncer in `transaction` mode only. Removal scheduled for June 20, 2026.

one of "transaction"

project_idstringrequired

The ID of the project this compute endpoint belongs to.

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

provisionerstringrequired
proxy_hoststringrequired

Deprecated. Use the `host` property instead.

region_idstringrequired

Cloud region where the resource's Postgres compute and storage reside (for example, `aws-us-east-1`). Valid values are returned by `GET /regions`.

settingsobjectrequired

A collection of settings for a compute endpoint

Show child attributes
pg_settingsobject

A raw representation of Postgres settings

pgbouncer_settingsobject

Deprecated. A raw representation of PgBouncer settings. Removal scheduled for June 20, 2026.

preload_librariesobjectPreloadLibraries ↑

The shared libraries to preload into the project's compute instances.

started_atstring · date-time

A timestamp indicating when the compute endpoint was last started

suspend_timeout_secondsinteger · int64required

Duration of inactivity in seconds after which the compute endpoint is automatically suspended. The value `0` means use the default value. The value `-1` means never suspend. The default value is `300` seconds (5 minutes). The minimum value is `60` seconds (1 minute). The maximum value is `604800` seconds (1 week). For more information, see [Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).

maximum 604800 · minimum -1

suspended_atstring · date-time

A timestamp indicating when the compute endpoint was last suspended

typestringrequired

Compute endpoint type. `read_write`: the primary read-write endpoint (one per branch). `read_only`: a read replica endpoint (multiple allowed per branch).

one of "read_only", "read_write"

updated_atstring · date-timerequired

A timestamp indicating when the compute endpoint was last updated

Example response
{
  "branch": {
    "active_time_seconds": 922200,
    "compute_time_seconds": 823880990,
    "cpu_used_sec": 461100,
    "created_at": "2022-11-30T19:09:48Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 72911987,
    "default": true,
    "id": "br-wispy-meadow-118737",
    "init_source": "parent-data",
    "name": "dev2",
    "parent_id": "br-aged-salad-637688",
    "parent_lsn": "0/1DE2850",
    "project_id": "spring-example-302709",
    "protected": false,
    "state_changed_at": "2022-11-30T20:09:48Z",
    "updated_at": "2022-12-01T19:53:05Z",
    "written_data_bytes": 542998300
  },
  "connection_uris": [
    {
      "connection_parameters": {
        "database": "string",
        "host": "string",
        "password": "",
        "pooler_host": "string",
        "role": "string"
      },
      "connection_uri": "string"
    }
  ],
  "databases": [
    {
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-11-30T18:25:15Z",
      "id": 834686,
      "name": "neondb",
      "owner_name": "casey",
      "updated_at": "2022-11-30T18:25:15Z"
    }
  ],
  "endpoints": [
    {
      "autoscaling_limit_max_cu": 1,
      "autoscaling_limit_min_cu": 1,
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-12-03T15:37:07Z",
      "creation_source": "console",
      "current_state": "init",
      "disabled": false,
      "host": "ep-silent-smoke-806639.us-east-2.aws.neon.tech",
      "id": "ep-silent-smoke-806639",
      "name": "My cool compute",
      "passwordless_access": true,
      "pending_state": "active",
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "project_id": "spring-example-302709",
      "provisioner": "k8s-neonvm",
      "proxy_host": "us-east-2.aws.neon.tech",
      "region_id": "aws-us-east-2",
      "settings": {
        "pg_settings": {}
      },
      "suspend_timeout_seconds": 0,
      "type": "read_write",
      "updated_at": "2022-12-03T15:37:07Z"
    }
  ],
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-11-15T20:02:00Z",
      "endpoint_id": "ep-silent-smoke-806639",
      "failures_count": 0,
      "id": "d8ac46eb-a757-42b1-9907-f78322ee394e",
      "project_id": "spring-example-302709",
      "status": "finished",
      "total_duration_ms": 200,
      "updated_at": "2022-11-15T20:02:02Z"
    }
  ],
  "project": {
    "active_time_seconds": 621440,
    "branch_logical_size_limit": 10,
    "branch_logical_size_limit_bytes": 10485760,
    "compute_time_seconds": 2485760,
    "consumption_period_end": "2022-12-01T00:00:00Z",
    "consumption_period_start": "2022-11-01T00:00:00Z",
    "cpu_used_sec": 155350,
    "created_at": "2022-12-13T01:30:55Z",
    "creation_source": "console",
    "data_storage_bytes_hour": 2831928,
    "data_transfer_bytes": 1000,
    "history_retention_seconds": 604800,
    "id": "spring-example-302709",
    "name": "spring-example-302709",
    "org_id": "org-morning-bread-81040908",
    "owner": {
      "branches_limit": 10,
      "email": "some@email.com",
      "name": "John Smith",
      "subscription_type": "scale"
    },
    "owner_id": "629982cc-de05-43db-ae16-28f2399c4910",
    "pg_version": 15,
    "platform_id": "aws",
    "provisioner": "k8s-pod",
    "proxy_host": "us-east-2.aws.neon.tech",
    "region_id": "aws-us-east-2",
    "store_passwords": true,
    "updated_at": "2022-12-13T01:30:55Z",
    "written_data_bytes": 193990002
  },
  "roles": [
    {
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-11-23T17:42:25Z",
      "name": "casey",
      "protected": false,
      "updated_at": "2022-11-23T17:42:25Z"
    }
  ]
}
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