Skip to content
You're viewing documentation for v2026.11.5-beta. It may be out of date.Go to latest
TimescaleDB Enterprise
Esc
↑↓navigate↵open⌘Jpreview

Get service health

Reads the service now and returns the verdict (health), with the rules of the stored verdict, and the result of each probe (probes) in the shape of its own endpoint. One call gives the data of the per-component endpoints. HAProxy, pgBackRest and the emergency reserve use the results that the health poller read in the last 5 minutes, when it has them. Calls for the same service at the same time share one reading. It does not read an error a second time and does not store the verdict. Like the Patroni endpoint, it sets a failed service to running when Patroni is healthy and the failed operation was a config apply. When the backup config is out of sync, pgbackrest is a not_applicable entry with no backups; /health/pgbackrest runs the probe. A service that is not running or failed reads unknown with no probes. It usually answers in a few seconds, and in at most 3 minutes when a probe does not return or other live checks run. The list and detail responses carry the stored verdict (health), which costs no probe.

GET/api/v1/database-services/{id}/health
Authorization
tse_sessionAPI key · cookierequired
Path parameters
idstringrequired
Responses
200

OK

healthServiceHealthResponserequired
Show properties
checked_atstring<date-time>

The time of the last real reading. Absent when there is none. When it is 15 minutes old or older, status is error with a reason that names the checks that did not run.

componentsComponentHealthResponse[]required
Show properties
Array of ComponentHealthResponse
keystringrequired

The stable key of the component: the path segment of its endpoint. Name is text for people and can change.

Allowed:patronietcdpgbouncerhaproxypgbackrestpostgresqlreservevip
messagestring
namestringrequired
statusstringrequired
Allowed:healthywarningerrorunknownnot_applicable
reasonstringrequired
sincestring<date-time>

The time the status last changed. Absent on a live reading.

statusstringrequired
Allowed:healthywarningerrorunknown
probesServiceProbesResponserequired
Show properties
etcdEtcdHealthResponse
Show properties
console_mesh_downboolean

The console reaches no enrolled server over the mesh, so the members were not checked.

errorstring
membersEtcdMemberHealth[]
Show properties
Array of EtcdMemberHealth
causestring

Why the member is not healthy: down (no mesh path), unverified (the check failed), or unhealthy (etcd says so). Empty when healthy.

Allowed:downunverifiedunhealthy
errorstring
healthybooleanrequired
hoststringrequired
overlay_ipstring
server_idstringrequired
statusstringrequired
Allowed:healthyunhealthyerror
haproxyHaproxyHealthResponse
Show properties
errorstring
membersHaproxyNodeHealth[]
Show properties
Array of HaproxyNodeHealth
backendsHaproxyBackendServer[]
Show properties
Array of HaproxyBackendServer
backendstringrequired
checkstring
serverstringrequired
statusstringrequired
errorstring
healthybooleanrequired
hoststringrequired
server_idstringrequired
statusstringrequired
Allowed:healthyunhealthyerrornot_applicable
patroniPatroniHealthResponse
Show properties
console_mesh_downboolean

The console reaches no enrolled server over the mesh, so the members were not checked.

errorstring
statusstringrequired
Allowed:healthyunhealthyerror
topologyClusterStatus
Show properties
membersMember[]required
Show properties
Array of Member
api_urlstring
hoststringrequired
laginteger<int64>
namestringrequired
pending_restartboolean
portinteger<int64>
rolestringrequired
server_idstring
statestringrequired
timelineinteger<int64>required
pgbackrestPgbackrestHealthResponse
Show properties
backup_runningbooleanrequired
backupsPgbackrestBackupInfo[]
Show properties
Array of PgbackrestBackupInfo
checksum_errorsboolean

True when pgBackRest found invalid page checksums in the backup: some data files of the database are corrupt

database_idinteger<int64>
database_size_bytesinteger<int64>required
labelstringrequired
olderboolean

True for a backup of a database id older than the newest of its repo, from before a PostgreSQL major upgrade. It restores only into a new service on pg_version, never in place

pg_versionstring
prior_checksum_errorsboolean

True when a backup that this backup depends on (its full, and the diff of an incr) has invalid page checksums. A restore of this backup restores the corrupt files of that backup too, so it is refused like a backup with checksum_errors

repointeger<int64>
size_bytesinteger<int64>required

Bytes that this backup stored in the repo, after compression. The files of the backups that it depends on are not included

start_timestringrequired
stop_timestringrequired
typestringrequired
wal_startstring
wal_stopstring
coverageStanzaCoverageJSON
Show properties
assumes_archivingbooleanrequired
earlieststringrequired
endstringrequired
nowstringrequired
reposRepoCoverageJSON[]required
Show properties
Array of RepoCoverageJSON
backupsCoveredBackupJSON[]required
Show properties
Array of CoveredBackupJSON
checksum_errorsboolean

True when pgBackRest found invalid page checksums in the backup, or in a backup that it depends on (its full, and the diff of an incr). A restore of it is refused unless allow_checksum_errors is set

labelstringrequired
stop_timestringrequired
current_tliinteger<int32>required
min 0
database_idinteger<int64>

The pgBackRest database id of this coverage

earlieststringrequired
grant_fingerprintstring

The license grant fingerprint of a fork or recover that restores this database id: the cluster that the copy has. Only a live scan of the backups gives it

kindstringrequired
Allowed:localremote
olderboolean

True for a database id older than the newest of the stanza, from before a PostgreSQL major upgrade. Its times restore only into a new service on pg_version, and its coverage ends at its newest backup

pg_versionstring

The PostgreSQL major of the database id

repointeger<int64>required
wal_maxstringrequired
wal_minstringrequired
errorstring
first_backup_pendingboolean

True when the service has no backups only because its first backup did not end yet: the backup runs, or an operation whose end starts a full backup (a deploy, a restore, a major upgrade step) runs or ended less than 15 minutes ago on the console clock. The service health counts no backups as healthy then.

stanzastring
statusstringrequired

not_applicable: the service has no active backup repo. not_deployed: the service is not running and no deploy of it completed, so pgbackrest info did not run.

Allowed:healthywarningerrornot_applicablenot_deployed
wal_maxstring
wal_minstring
pgbouncerPgbouncerHealthResponse
Show properties
errorstring
serversPgbouncerNodeHealth[]
Show properties
Array of PgbouncerNodeHealth
errorstring
healthybooleanrequired
hoststringrequired
poolsPgbouncerPoolInfo[]
Show properties
Array of PgbouncerPoolInfo
cl_activeinteger<int64>required
cl_waitinginteger<int64>required
databasestringrequired
pool_modestringrequired
userstringrequired
server_idstringrequired
statusstringrequired
Allowed:healthyunhealthyerror
postgresqlPostgresqlInfoResponse
Show properties
connectionsConnectionsInfo
Show properties
activeinteger<int64>required
idleinteger<int64>required
maxinteger<int64>required
totalinteger<int64>required
databasesDatabaseInfo[]
Show properties
Array of DatabaseInfo
namestringrequired
size_bytesinteger<int64>required
errorstring
membersPostgresqlMemberInfo[]required
Show properties
Array of PostgresqlMemberInfo
errorstring
namestringrequired
patroni_versionstring
postmaster_start_timestring
rolestringrequired
server_idstring
server_versioninteger<int64>
statestringrequired
stats_errorstring
total_size_bytesinteger<int64>
uptime_secondsinteger<int64>
reserveReserveHealthResponse
Show properties
errorstring
nodesReserveNodeHealth[]
Show properties
Array of ReserveNodeHealth
detailstring
errorstring
expected_bytesinteger<int64>required
expected_countinteger<int64>required
filesReserveFile[]required
Show properties
Array of ReserveFile
namestringrequired
size_bytesinteger<int64>required
hoststringrequired
rootReserveRoot
Show properties
dirstringrequired
expected_bytesinteger<int64>required
mountstringrequired

Mount point of the disk that holds postgresql.conf

size_bytesinteger<int64>required

Size of the root file; 0 when it is missing

statusstringrequired
Allowed:okdegraded
server_idstringrequired
statusstringrequired
Allowed:okdegradednot_provisionedunknown
statusstringrequired
Allowed:okdegradednot_provisionedunknown
default

Error

codestring

Stable code of the refusal, when the route has codes

detailsstring[]

Additional detail, e.g. per-field validation failures

errorstringrequired

Human-readable error message

Request
curl -X GET 'https://console.example.com/api/v1/database-services/string/health' \
  -H 'Cookie: tse_session=YOUR_API_KEY' \
  -H 'Accept: application/json'
Response
{
  "health": {
    "checked_at": "2019-08-24T14:15:22Z",
    "components": [
      {
        "key": "patroni",
        "message": "string",
        "name": "string",
        "status": "healthy"
      }
    ],
    "reason": "string",
    "since": "2019-08-24T14:15:22Z",
    "status": "healthy"
  },
  "probes": {
    "etcd": {
      "console_mesh_down": true,
      "error": "string",
      "members": [
        {
          "cause": "down",
          "error": "string",
          "healthy": true,
          "host": "string",
          "overlay_ip": "string",
          "server_id": "string"
        }
      ],
      "status": "healthy"
    },
    "haproxy": {
      "error": "string",
      "members": [
        {
          "backends": [
            {
              "backend": "string",
              "check": "string",
              "server": "string",
              "status": "string"
            }
          ],
          "error": "string",
          "healthy": true,
          "host": "string",
          "server_id": "string"
        }
      ],
      "status": "healthy"
    },
    "patroni": {
      "console_mesh_down": true,
      "error": "string",
      "status": "healthy",
      "topology": {
        "members": [
          {
            "api_url": "string",
            "host": "string",
            "lag": 0,
            "name": "string",
            "pending_restart": true,
            "port": 0,
            "role": "string",
            "server_id": "string",
            "state": "string",
            "timeline": 0
          }
        ]
      }
    },
    "pgbackrest": {
      "backup_running": true,
      "backups": [
        {
          "checksum_errors": true,
          "database_id": 0,
          "database_size_bytes": 0,
          "label": "string",
          "older": true,
          "pg_version": "string",
          "prior_checksum_errors": true,
          "repo": 0,
          "size_bytes": 0,
          "start_time": "string",
          "stop_time": "string",
          "type": "string",
          "wal_start": "string",
          "wal_stop": "string"
        }
      ],
      "coverage": {
        "assumes_archiving": true,
        "earliest": "string",
        "end": "string",
        "now": "string",
        "repos": [
          {
            "backups": [
              {
                "checksum_errors": true,
                "label": "string",
                "stop_time": "string"
              }
            ],
            "current_tli": 0,
            "database_id": 0,
            "earliest": "string",
            "grant_fingerprint": "string",
            "kind": "local",
            "older": true,
            "pg_version": "string",
            "repo": 0,
            "wal_max": "string",
            "wal_min": "string"
          }
        ]
      },
      "error": "string",
      "first_backup_pending": true,
      "stanza": "string",
      "status": "healthy",
      "wal_max": "string",
      "wal_min": "string"
    },
    "pgbouncer": {
      "error": "string",
      "servers": [
        {
          "error": "string",
          "healthy": true,
          "host": "string",
          "pools": [
            {
              "cl_active": 0,
              "cl_waiting": 0,
              "database": "string",
              "pool_mode": "string",
              "user": "string"
            }
          ],
          "server_id": "string"
        }
      ],
      "status": "healthy"
    },
    "postgresql": {
      "connections": {
        "active": 0,
        "idle": 0,
        "max": 0,
        "total": 0
      },
      "databases": [
        {
          "name": "string",
          "size_bytes": 0
        }
      ],
      "error": "string",
      "members": [
        {
          "error": "string",
          "name": "string",
          "patroni_version": "string",
          "postmaster_start_time": "string",
          "role": "string",
          "server_id": "string",
          "server_version": 0,
          "state": "string"
        }
      ],
      "stats_error": "string",
      "total_size_bytes": 0,
      "uptime_seconds": 0
    },
    "reserve": {
      "error": "string",
      "nodes": [
        {
          "detail": "string",
          "error": "string",
          "expected_bytes": 0,
          "expected_count": 0,
          "files": [
            {
              "name": "string",
              "size_bytes": 0
            }
          ],
          "host": "string",
          "root": {
            "dir": "string",
            "expected_bytes": 0,
            "mount": "string",
            "size_bytes": 0,
            "status": "ok"
          },
          "server_id": "string",
          "status": "ok"
        }
      ],
      "status": "ok"
    }
  }
}