API Reference

Projects

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Services

Manage services and their associated actions.

List All Services

GET/projects/{project_id}/services

Create a Service

POST/projects/{project_id}/services

Get a Service

GET/projects/{project_id}/services/{service_id}

Delete a Service

DELETE/projects/{project_id}/services/{service_id}

Start a Service

POST/projects/{project_id}/services/{service_id}/start

Stop a Service

POST/projects/{project_id}/services/{service_id}/stop

Attach Service to VPC

POST/projects/{project_id}/services/{service_id}/attachToVPC

Detach Service from VPC

POST/projects/{project_id}/services/{service_id}/detachFromVPC

Resize a Service

POST/projects/{project_id}/services/{service_id}/resize

Enable Connection Pooler for a Service

POST/projects/{project_id}/services/{service_id}/enablePooler

Disable Connection Pooler for a Service

POST/projects/{project_id}/services/{service_id}/disablePooler

Fork a Service

POST/projects/{project_id}/services/{service_id}/forkService

Update Service Password

POST/projects/{project_id}/services/{service_id}/updatePassword

Set Environment for a Service

POST/projects/{project_id}/services/{service_id}/setEnvironment

Get service logs

GET/projects/{project_id}/services/{service_id}/logs

Change HA configuration for a Service

POST/projects/{project_id}/services/{service_id}/setHA

Rename a Service

POST/projects/{project_id}/services/{service_id}/rename

Enable Data Tiering for a Service

POST/projects/{project_id}/services/{service_id}/enableDataTiering

ModelsExpand Collapse

ConnectionPooler object { endpoint }

Connection pooler configuration for a service.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

Endpoint object { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

EnvironmentTag = "DEV" or "PROD"

The environment tag for the service:

• DEV: a development environment
• PROD: a production environment

One of the following:

"DEV"

"PROD"

ResizeInput object { cpu_millis, memory_gbs }

At least one of cpu_millis, memory_gbs, or iops must be provided. cpu_millis and memory_gbs must be provided together.

cpu_millis: optional string

The new CPU allocation in milli-cores.

memory_gbs: optional string

The new memory allocation in gigabytes.

Service object { created, name, project_id, 16 more }

A database service and its current configuration.

created: string

Creation timestamp.

formatdate-time

name: string

The name of the service.

project_id: string

The project this service belongs to.

region_code: string

The cloud region where the service is hosted.

resources: array of object { id, spec }

List of resources allocated to the service.

id: optional string

Resource identifier.

spec: optional object { cpu_millis, memory_gbs, volume_type }

Resource specification.

cpu_millis: optional number

CPU allocation in millicores.

memory_gbs: optional number

Memory allocation in gigabytes.

volume_type: optional string

Type of storage volume.

service_id: string

The unique identifier for the service.

service_type: "TIMESCALEDB" or "POSTGRES" or "VECTOR"

The type of the service:

• TIMESCALEDB: a TimescaleDB service (PostgreSQL with the TimescaleDB extension)
• POSTGRES: a standard PostgreSQL service

VECTOR is deprecated and should not be used.

One of the following:

"TIMESCALEDB"

"POSTGRES"

"VECTOR"

status: "QUEUED" or "DELETING" or "CONFIGURING" or 8 more

The current deployment status of the service:

• QUEUED: the create request has been submitted and is queued
• DELETING: the service is being deleted
• CONFIGURING: the service is up but still completing configuration
• READY: fully configured and serving traffic
• DELETED: the service has been deleted
• UNSTABLE: the service was ready but is not currently reachable
• PAUSING: the service is being paused
• PAUSED: the service is paused (temporarily shut down)
• RESUMING: the service is resuming after being paused
• UPGRADING: the service is being updated

OPTIMIZING is deprecated and should not be used.

One of the following:

"QUEUED"

"DELETING"

"CONFIGURING"

"READY"

"DELETED"

"UNSTABLE"

"PAUSING"

"PAUSED"

"RESUMING"

"UPGRADING"

"OPTIMIZING"

connection_pooler: optional ConnectionPooler { endpoint }

Connection pooler configuration for a service.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

data_tiering: optional object { enabled }

Data tiering configuration for a service.

enabled: optional boolean

Whether tiered storage is enabled for this service.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

forked_from: optional object { is_standby, project_id, service_id }

The service this service was forked from.

is_standby: optional boolean

Whether this service is a standby of the parent service.

project_id: optional string

The project of the parent service.

service_id: optional string

The ID of the parent service.

ha_replicas: optional object { replica_count, sync_replica_count }

High-availability replica configuration for a service.

replica_count: optional number

Number of high-availability replicas (all replicas are asynchronous by default).

sync_replica_count: optional number

Number of synchronous high-availability replicas.

initial_password: optional string

The initial password for the service.

formatpassword

metadata: optional object { environment }

Additional metadata for the service.

environment: optional string

Environment tag for the service.

metrics: optional object { memory_mb, milli_cpu, storage_mb }

Resource usage metrics for the service.

memory_mb: optional number

Memory usage in megabytes.

milli_cpu: optional number

CPU usage in millicores.

storage_mb: optional number

Storage usage in megabytes.

read_replica_sets: optional array of ReadReplicaSet { id, cpu_millis, memory_gbs, 7 more }

The read replica sets attached to the service.

id: string

The unique identifier for the read replica set.

cpu_millis: number

CPU allocation in milli-cores.

memory_gbs: number

Memory allocation in gigabytes.

name: string

The name of the read replica set.

nodes: number

Number of nodes in the replica set.

service_id: string

The ID of the parent service this read replica set was created from.

status: "creating" or "active" or "resizing" or 2 more

The current status of the read replica set:

• creating: the replica set is being provisioned
• active: the replica set is provisioned and serving traffic
• resizing: the replica set is being resized
• deleting: the replica set is being deleted
• error: the replica set is in an error state

One of the following:

"creating"

"active"

"resizing"

"deleting"

"error"

connection_pooler: optional ConnectionPooler { endpoint }

Connection pooler configuration for a service.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

metadata: optional object { environment }

Additional metadata for the read replica set.

environment: optional string

Environment tag for the read replica set.

vpc_endpoint: optional object { host, port, vpc_id }

VPC endpoint configuration for connecting to a service over VPC peering.

host: optional string

The hostname for connecting to the service over VPC peering.

port: optional number

The port for connecting to the service over VPC peering.

vpc_id: optional string

The ID of the VPC the endpoint is associated with.

DeprecatedvpcEndpoint: optional object { host, port, vpc_id }

VPC endpoint configuration for connecting to a service over VPC peering.

host: optional string

The hostname for connecting to the service over VPC peering.

port: optional number

The port for connecting to the service over VPC peering.

vpc_id: optional string

The ID of the VPC the endpoint is associated with.

ServiceVpcInput object { vpc_id }

Parameters for attaching a service to a VPC.

vpc_id: string

The ID of the VPC to attach the service to.

SetEnvironmentInput object { environment }

Parameters for setting a service’s environment.

environment: "PROD" or "DEV"

The target environment for the service:

• PROD: a production environment
• DEV: a development environment

One of the following:

"PROD"

"DEV"

ServiceListResponse = array of Service { created, name, project_id, 16 more }

created: string

Creation timestamp.

formatdate-time

name: string

The name of the service.

project_id: string

The project this service belongs to.

region_code: string

The cloud region where the service is hosted.

resources: array of object { id, spec }

List of resources allocated to the service.

id: optional string

Resource identifier.

spec: optional object { cpu_millis, memory_gbs, volume_type }

Resource specification.

cpu_millis: optional number

CPU allocation in millicores.

memory_gbs: optional number

Memory allocation in gigabytes.

volume_type: optional string

Type of storage volume.

service_id: string

The unique identifier for the service.

service_type: "TIMESCALEDB" or "POSTGRES" or "VECTOR"

The type of the service:

• TIMESCALEDB: a TimescaleDB service (PostgreSQL with the TimescaleDB extension)
• POSTGRES: a standard PostgreSQL service

VECTOR is deprecated and should not be used.

One of the following:

"TIMESCALEDB"

"POSTGRES"

"VECTOR"

status: "QUEUED" or "DELETING" or "CONFIGURING" or 8 more

The current deployment status of the service:

• QUEUED: the create request has been submitted and is queued
• DELETING: the service is being deleted
• CONFIGURING: the service is up but still completing configuration
• READY: fully configured and serving traffic
• DELETED: the service has been deleted
• UNSTABLE: the service was ready but is not currently reachable
• PAUSING: the service is being paused
• PAUSED: the service is paused (temporarily shut down)
• RESUMING: the service is resuming after being paused
• UPGRADING: the service is being updated

OPTIMIZING is deprecated and should not be used.

One of the following:

"QUEUED"

"DELETING"

"CONFIGURING"

"READY"

"DELETED"

"UNSTABLE"

"PAUSING"

"PAUSED"

"RESUMING"

"UPGRADING"

"OPTIMIZING"

connection_pooler: optional ConnectionPooler { endpoint }

Connection pooler configuration for a service.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

data_tiering: optional object { enabled }

Data tiering configuration for a service.

enabled: optional boolean

Whether tiered storage is enabled for this service.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

forked_from: optional object { is_standby, project_id, service_id }

The service this service was forked from.

is_standby: optional boolean

Whether this service is a standby of the parent service.

project_id: optional string

The project of the parent service.

service_id: optional string

The ID of the parent service.

ha_replicas: optional object { replica_count, sync_replica_count }

High-availability replica configuration for a service.

replica_count: optional number

Number of high-availability replicas (all replicas are asynchronous by default).

sync_replica_count: optional number

Number of synchronous high-availability replicas.

initial_password: optional string

The initial password for the service.

formatpassword

metadata: optional object { environment }

Additional metadata for the service.

environment: optional string

Environment tag for the service.

metrics: optional object { memory_mb, milli_cpu, storage_mb }

Resource usage metrics for the service.

memory_mb: optional number

Memory usage in megabytes.

milli_cpu: optional number

CPU usage in millicores.

storage_mb: optional number

Storage usage in megabytes.

read_replica_sets: optional array of ReadReplicaSet { id, cpu_millis, memory_gbs, 7 more }

The read replica sets attached to the service.

id: string

The unique identifier for the read replica set.

cpu_millis: number

CPU allocation in milli-cores.

memory_gbs: number

Memory allocation in gigabytes.

name: string

The name of the read replica set.

nodes: number

Number of nodes in the replica set.

service_id: string

The ID of the parent service this read replica set was created from.

status: "creating" or "active" or "resizing" or 2 more

The current status of the read replica set:

• creating: the replica set is being provisioned
• active: the replica set is provisioned and serving traffic
• resizing: the replica set is being resized
• deleting: the replica set is being deleted
• error: the replica set is in an error state

One of the following:

"creating"

"active"

"resizing"

"deleting"

"error"

connection_pooler: optional ConnectionPooler { endpoint }

Connection pooler configuration for a service.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

metadata: optional object { environment }

Additional metadata for the read replica set.

environment: optional string

Environment tag for the read replica set.

vpc_endpoint: optional object { host, port, vpc_id }

VPC endpoint configuration for connecting to a service over VPC peering.

host: optional string

The hostname for connecting to the service over VPC peering.

port: optional number

The port for connecting to the service over VPC peering.

vpc_id: optional string

The ID of the VPC the endpoint is associated with.

DeprecatedvpcEndpoint: optional object { host, port, vpc_id }

VPC endpoint configuration for connecting to a service over VPC peering.

host: optional string

The hostname for connecting to the service over VPC peering.

port: optional number

The port for connecting to the service over VPC peering.

vpc_id: optional string

The ID of the VPC the endpoint is associated with.

ServiceAttachToVpcResponse object { message }

message: optional string

ServiceDetachFromVpcResponse object { message }

message: optional string

ServiceEnablePoolerResponse object { message }

message: optional string

ServiceDisablePoolerResponse object { message }

message: optional string

ServiceSetEnvironmentResponse object { message }

message: optional string

ServiceLogsResponse object { logs, entries, last_cursor, lastCursor }

The logs for a service.

Deprecatedlogs: array of string

Array of log message strings. Preserved for backwards compatibility.

entries: optional array of object { message, severity, timestamp }

Structured log entries with timestamp and severity metadata. Entries are in the same order as logs and can be used in place of it by callers that need structured data.

message: string

Log message text.

severity: string

PostgreSQL severity level (e.g. LOG, WARNING, ERROR, FATAL).

timestamp: string

Timestamp of the log entry (RFC3339 format).

formatdate-time

last_cursor: optional string

Opaque cursor for the next page of results. Present when more log entries exist older than the last entry in this response. Pass this value as the cursor query parameter to retrieve the next page. Absent when there are no further results.

DeprecatedlastCursor: optional string

Deprecated. Use last_cursor instead.

ServicesReplica Sets

Manage read replica sets and their associated actions.

Get Read Replica Sets

GET/projects/{project_id}/services/{service_id}/replicaSets

Create a Read Replica Set

POST/projects/{project_id}/services/{service_id}/replicaSets

Delete a Read Replica Set

DELETE/projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}

Resize a Read Replica Set

POST/projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/resize

Enable Connection Pooler for a Read Replica

POST/projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler

Disable Connection Pooler for a Read Replica

POST/projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler

Set Environment for a Read Replica

POST/projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment

ModelsExpand Collapse

ReadReplicaSet object { id, cpu_millis, memory_gbs, 7 more }

A set of read replicas for a service.

id: string

The unique identifier for the read replica set.

cpu_millis: number

CPU allocation in milli-cores.

memory_gbs: number

Memory allocation in gigabytes.

name: string

The name of the read replica set.

nodes: number

Number of nodes in the replica set.

service_id: string

The ID of the parent service this read replica set was created from.

status: "creating" or "active" or "resizing" or 2 more

The current status of the read replica set:

• creating: the replica set is being provisioned
• active: the replica set is provisioned and serving traffic
• resizing: the replica set is being resized
• deleting: the replica set is being deleted
• error: the replica set is in an error state

One of the following:

"creating"

"active"

"resizing"

"deleting"

"error"

connection_pooler: optional ConnectionPooler { endpoint }

Connection pooler configuration for a service.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

metadata: optional object { environment }

Additional metadata for the read replica set.

environment: optional string

Environment tag for the read replica set.

ReplicaSetRetrieveReplicaSetsResponse = array of ReadReplicaSet { id, cpu_millis, memory_gbs, 7 more }

id: string

The unique identifier for the read replica set.

cpu_millis: number

CPU allocation in milli-cores.

memory_gbs: number

Memory allocation in gigabytes.

name: string

The name of the read replica set.

nodes: number

Number of nodes in the replica set.

service_id: string

The ID of the parent service this read replica set was created from.

status: "creating" or "active" or "resizing" or 2 more

The current status of the read replica set:

• creating: the replica set is being provisioned
• active: the replica set is provisioned and serving traffic
• resizing: the replica set is being resized
• deleting: the replica set is being deleted
• error: the replica set is in an error state

One of the following:

"creating"

"active"

"resizing"

"deleting"

"error"

connection_pooler: optional ConnectionPooler { endpoint }

Connection pooler configuration for a service.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

endpoint: optional Endpoint { host, port }

A network endpoint for connecting to a service.

host: optional string

The hostname of the endpoint.

port: optional number

The port of the endpoint.

metadata: optional object { environment }

Additional metadata for the read replica set.

environment: optional string

Environment tag for the read replica set.

ReplicaSetResizeResponse object { message }

message: optional string

ReplicaSetEnablePoolerResponse object { message }

message: optional string

ReplicaSetDisablePoolerResponse object { message }

message: optional string

ReplicaSetSetEnvironmentResponse object { message }

message: optional string

ServicesMetrics

Manage services and their associated actions.

List available metric series

GET/projects/{project_id}/services/{service_id}/metrics/available-series

Get a metric series

POST/projects/{project_id}/services/{service_id}/metrics/series

ModelsExpand Collapse

MetricAvailableSeriesResponse = array of string

MetricSeriesResponse = array of object { data, labels }

data: array of object { time, value }

Per-bucket data points for this label set.

time: string

The bucket start timestamp.

formatdate-time

value: optional number

The aggregated value at this bucket, or null for a gap bucket with no collected data. Gap buckets are still emitted (one entry per bucket in the window), so this is null rather than omitted.

formatdouble

labels: map[string]

Label set identifying this series. The key set depends on the metric (e.g. role, ordinal).

ServicesMetricsDetails

Manage services and their associated actions.

Get details about a metric

GET/projects/{project_id}/services/{service_id}/metrics/details/{metric_name}

ModelsExpand Collapse

DetailRetrieveResponse object { default_agg, description, labels, 2 more }

Descriptive metadata for a metric series — what it is, not its data. Some series don’t have full metadata yet: type and default_agg may be null and description/labels may be empty, but every field below is always present in the response.

default_agg: "RATE" or "INCREASE" or "SUM" or 10 more

Aggregation function applied to raw/pre-aggregated samples when collapsing them into one value per output bucket.

• RATE: counter-reset-aware per-second rate of change.
• INCREASE: counter-reset-aware total increase over the bucket.
• SUM: sum of samples in the bucket.
• AVG: mean of samples in the bucket.
• MIN: minimum sample in the bucket.
• MAX: maximum sample in the bucket.
• MIN_TOTAL / MAX_TOTAL: minimum/maximum of the bucket’s samples added together across every series first — for a metric with labels (e.g. one series per database) where the combined total, not any single series’ own extremum, is the meaningful quantity (e.g. peak of total connections across all databases). MIN/MAX give the single most extreme individual series instead, which is the right answer when the metric is itself an extremum or a timestamp (e.g. longest-running transaction).
• COUNT: number of samples in the bucket.
• P50 / P90 / P99: approximate percentiles.
• LAST: the most recent sample in the bucket.

One of the following:

"RATE"

"INCREASE"

"SUM"

"AVG"

"MIN"

"MAX"

"MIN_TOTAL"

"MAX_TOTAL"

"COUNT"

"P50"

"P90"

"P99"

"LAST"

description: string

What this metric measures, or empty if undocumented.

labels: array of object { description, name }

All labels this metric can be filtered or grouped by: its own labels (e.g. datname on pg_stat_database_*) plus the region/role/ordinal labels most metrics also carry. Some metrics only attach a subset of those — e.g. pgbouncer-sourced metrics only get region, not role/ordinal.

description: string

What this label identifies, or empty if undocumented.

name: string

The label’s key.

metric_name: string

Metric series name.

type: "GAUGE" or "COUNTER" or "HISTOGRAM" or "SUMMARY"

The shape of a metric’s underlying data.

• GAUGE: a value that can go up or down (e.g. a current connection count).
• COUNTER: a value that only increases until it resets (e.g. total queries run).
• HISTOGRAM: a distribution of observed values grouped into ranges.
• SUMMARY: a distribution of observed values summarized by quantile.

One of the following:

"GAUGE"

"COUNTER"

"HISTOGRAM"

"SUMMARY"