Skip to main content
GET
Get a managed service instance

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
instance_id
string<uuid>
required

Response

Authorised durable installation metadata and scoped deployment evidence.

​
id
string<uuid>
required
​
package_version_id
string<uuid>
required
​
cluster_id
string<uuid>
required
​
cluster_name
string
required

The service cluster's name as it reads now, for display; cluster_id is the identity.

​
cluster_deleted
boolean
required

The platform recorded the service cluster deleted, which removed the service with it. The instance stays listed so it can be retired, which only releases its name; its state reads unknown, its readiness stale, and health and connection are null.

​
state
enum<string>
required

The instance's lifecycle in one word, folded at read time from deployment_state, health, readiness and retirement; those fields stay the evidence. released: the instance was released and its name is free. retiring: a confirmed retirement is removing it. failed: its admission or deployment operation failed. deploying: it is being installed, or its workload is rolling out. serving: the platform last observed its workload serving and no readiness check found it failing. degraded: an observation or readiness check found it not serving, or a namespace quota refuses its pods. deployed: its deployment finished and nothing observes its health (a package that is not a first-party engine, or one the health loop has not reached); not a statement that it serves. unknown: the recorded evidence establishes none of these. Precedence is released, retiring, failed, deploying, then the health-based states.

Available options:
deploying,
deployed,
serving,
degraded,
failed,
retiring,
released,
unknown
​
admission_operation_id
string<uuid>
required
​
name
string
required
​
region
string
required

Physical cloud region of the placement, for example eu-north-1. It locates infrastructure; it is not the data-location promise, which is data_boundary.

​
data_boundary
string
required

Boundary the data is permitted to stay within, for example eu. Sharing a service across clusters is decided by this boundary, never by the physical region.

​
generation
integer<int64>
required
Required range: x >= 1
​
mode
enum<string>
required
Available options:
customer,
existing,
hosted
​
requested_destinations
object[]
required

Requested destinations from the durable plan; not proof of a live service connection.

​
consumers
object[]
required

The reviewed plan's consumers with their ids: exactly the set a retirement request names in disconnect_consumer_ids. Reviewed intent, not proof of a live connection.

​
deployment_operation_id
string<uuid> | null
required

Present only when current execution evidence matches the stored receipt and organisation/cluster scope.

​
deployment_state
enum<string>
required
Available options:
accepted,
admission_failed,
deploying,
deployment_failed,
verification_pending,
unknown,
released
​
readiness
enum<string>
required

Whether a consumer can use the service, from a scoped consumer-path canary every five minutes: a pod in the instance namespace using the generated credentials by Secret reference the way a consumer would - for PostgreSQL logging in and running SELECT 1, for Valkey, NATS, OpenSearch, the S3 store, VictoriaLogs and VictoriaMetrics writing, reading and deleting a probe-owned record; a result stands fifteen minutes. unverified: no canary covers this instance (a package that is not a first-party engine, a hosted, released or later-generation instance, one with no deployment receipt, or an engine other than PostgreSQL on a cluster whose agent cannot run the canary yet, which readiness_check.reason names); a successful deployment is not readiness. verifying: covered, and no canary has established readiness yet - none has run, or the service is still deploying or inside its first start's grace window. ready: an unexpired canary passed. degraded: an unexpired canary ran and failed after the service had its chance to start. stale: readiness cannot currently be established - the canary could not run (no agent, the cluster unavailable, the canary pod refused or not finishing) or its last result expired; an expired ready is never reported.

Available options:
unverified,
verifying,
ready,
degraded,
stale
​
readiness_check
object | null
required

The canary evidence behind readiness, folded against the database clock at read time. Null when no canary has run at this generation. A canary that could not run leaves an unexpired pass or failure standing until it expires, so observed_at is when the standing result was observed, not necessarily the latest attempt. When readiness is unverified because the cluster's agent cannot run the engine's canary, observed_at, expires_at and last_passed_at are null and reason names the agent upgrade. Never carries a probe log or a credential.

​
created_at
string<date-time>
required
​
released_at
string<date-time> | null
required
​
evidence_updated_at
string<date-time> | null
required
​
connection
object | null
required

Where a first-party engine instance is reached inside its cluster and which Secret in its namespace holds the credentials the engine generated. Derived from the engine profile, not observed; null for any other package, and for a released instance, whose retirement deleted the namespace and the Secret.

​
health
object | null
required

Health as the platform last observed it from the service cluster's synced state: whether the engine's workload reports ready, its Service and credentials Secret exist, and the stack that owns it is still deployed. It is not readiness - no consumer connection is proven. Evidence past expires_at reads unknown, folded against the database clock at read time, so a stopped observer never leaves a stale serving. Null when nothing has observed this generation: a package that is not a first-party engine, an instance not deployed yet, a released instance, or one not observed yet.

​
retirement
object | null
required

The latest confirmed retirement, running or settled; null when none was ever confirmed. A settled outcome other than retired left the service and its name in place.

​
client_access
object | null

Whether the service's client network policy admits every connected application. Read only for a single instance; absent in a listing, for a released instance and for a stack the cluster does not run.

​
disconnections
object

The consumers a confirmed disconnection is removing from the service and has not finished with; they are no longer among consumers. Read only for a single instance; absent in a listing.

​
role_repair
string

The plain sentence the role repair lane last left for the service as a whole: the last time it re-applied the owner credential postgresql-app (because the readiness canary was refused for authentication, which a role acting as app can cause and which also undoes a password set on app by hand), or why it stopped re-applying it or re-rendering the role variables until a person looks. Absent when there is nothing to say, and for a service without roles.

​
abandoned_roles
object[]

What revocations given up at a bound left for a person: roles of disconnected applications, no longer any binding's credential, rendered unable to log in (never absent, which would not apply NOLOGIN) so they cannot log in whether or not they are ever dropped; and Secrets of roles already gone that the cluster's inventory still lists. Absent when there are none and when they could not be read (abandoned_roles_note says so then).

​
abandoned_roles_note
string

Set when the abandoned roles could not be read: the list is unknown, not empty.