Report this engine VM's state (db-agent).
curl --request POST \ --url https://stratum.example.com/v1/db-agent/status \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "generation": 1, "engineState": "initializing", "role": "primary", "engineVersion": "example", "dataMounted": true, "dataDevice": "example", "diskUsedPercent": 1, "diskSizeBytes": 1, "dataDeviceBytes": 1, "parametersGeneration": 1, "pendingRestart": true, "parametersError": "example", "extensions": { "applied": [ "example" ], "error": "example" }, "completedOperation": "example", "failedOperation": "example", "failedOperationError": "example", "masterPasswordVersionId": "example", "backup": { "snapshotId": "example", "phase": "started", "startLsn": "example", "stopLsn": "example", "startWal": "example", "stopWal": "example", "startedAt": "2026-04-15T12:00:00Z", "stoppedAt": "2026-04-15T12:00:00Z", "error": "example" }, "walArchive": { "lastArchivedWal": "example", "lastArchivedAt": "2026-04-15T12:00:00Z", "spoolPending": 1, "lastError": "example", "lastFailedWal": "example", "lastFailedAt": "2026-04-15T12:00:00Z", "failedCount": 1 }, "recovery": { "snapshotId": "example", "phase": "recovering", "completedAt": "2026-04-15T12:00:00Z", "error": "example" }, "replication": { "inRecovery": true, "walReceiverUp": true, "receiveLsn": "example", "replayLsn": "example", "currentLsn": "example", "standbyConnected": true, "syncState": "example", "lagBytes": 1, "error": "example" }, "walLevel": "example", "blueGreen": { "deploymentId": "example", "role": "example", "phase": "example", "preconditions": [ { "code": "example", "detail": "example" } ], "slots": [ { "database": "example", "name": "example", "confirmedFlushLsn": "example", "lagBytes": 1, "active": true } ], "fenced": true, "fenceLsn": "example", "subscriptions": [ { "database": "example", "name": "example", "enabled": true, "workerUp": true, "receivedLsn": "example", "latestEndLsn": "example", "error": "example" } ], "finalized": true, "error": "example" }, "agentVersion": "example", "message": "example" }'The agent’s observed state: whether the data volume is mounted,
whether the engine is running, its role and version, the parameter
generation it has applied, disk usage and the pending operation it
completed. The db reconciler reads the latest report on every pass;
available is only ever written from a report that says the engine is
up. Own-instance only (403 NOT_OWN_INSTANCE). Cedar-gated on
db:AgentStatus.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”The engine VM’s observed state.
object
The desired generation this report answers.
postgres --version as observed.
The data volume’s size as the guest kernel sees it; the agent grows the filesystem to it before reporting.
The parameter generation the running engine has applied.
pg_settings.pending_restart: a static parameter changed and waits for a restart.
Why the rendered parameters were NOT applied: a
shared_preload_libraries entry whose .so this engine image does
not carry. The engine keeps running the configuration it has rather
than restarting into one that cannot start.
The engine’s word on the curated extensions, observed in pg_extension.
object
The extensions that exist in every database they belong in.
The engine’s own words for one it would not create or drop.
The pending operation the agent has just completed, if any.
A pending operation the engine refused (apply_master_password when the role change failed); the control plane gives it up instead of waiting out the rotation window.
The engine’s own words for failedOperation, never carrying a secret.
The secret version whose password the master role holds — the agent’s confirmation of an apply.
The engine’s side of the snapshot handshake.
object
The archive’s position — the last segment the agent SHIPPED to the bucket (lastArchivedAt is the instance’s latestRestorableTime), the spool’s backlog and last shipping error, and the engine archiver’s own failures.
object
The replay’s report on a restored instance.
object
The engine’s side of the stream on a Multi-AZ member: the OBSERVED role (inRecovery, whatever the document asked — a promoted standby says false before the members are swapped), the standby’s receiver and replay lag, or the primary’s view of its standby (pg_stat_replication).
object
Pg_stat_replication’s sync_state of the named standby (sync, async, potential, quorum); empty when it is not connected.
Primary: WAL the standby has not replayed. Standby: received but not yet replayed.
SHOW wal_level on a running engine in a deployment (waits for logical).
The engine’s side of a blue/green deployment: the publisher’s preconditions (nothing is built while any remain), its slots’ positions and lag, the fence and its LSN; the subscriber’s subscriptions and whether it finalized.
object
object
object
object
A short human-readable note (the last error, for instance).
Responses
Section titled “Responses”Recorded.
Bad request.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Authenticated but not authorized.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Resource not found.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}