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

List servers

Returns every registered server with its state. Set live to read the reachability of each server now.

GET/api/v1/servers
Authorization
tse_sessionAPI key · cookierequired
Query parameters
liveboolean

Read the reachability of each enrolled server now and store it before the list, instead of the reading of the health poller (at most one minute old).

Responses
200

OK

Array of ServerResponse
cleaning_upbooleanrequired
cleanup_errorstring
cleanup_kindstring
Allowed:deploy_refusal
cleanup_pendingbooleanrequired
cleanup_sincestring
created_atstringrequired
database_servicesDatabaseServiceAssignmentResponse[]required
Show properties
Array of DatabaseServiceAssignmentResponse
database_service_idstringrequired
database_service_namestringrequired
rolestringrequired
demobooleanrequired
enroll_statestringrequired
Allowed:pendingenrolledremoved
headscale_node_idstring
healthServerHealthResponse
Show properties
checked_atstring<date-time>

The time of the last reading. Absent when there is none. When it is 15 minutes old or older, status is error.

notesServerHealthNoteResponse[]required

The current note of each component that the console checked on the server. Empty when the server has no reading for 15 minutes, and while the console cannot reach the mesh: the notes are then old.

Show properties
Array of ServerHealthNoteResponse
causestring

Why the note is not healthy: unreachable (no mesh path), unhealthy (the component says so), or unverified (the check failed).

Allowed:unreachableunhealthyunverified
componentstringrequired
Allowed:reachabilitypatronietcdpgbouncerhaproxyreserve
messagestring
sincestring<date-time>required

The time the status of the note last changed.

statusstringrequired
Allowed:healthywarningerrorunknown
reasonstringrequired
sincestring<date-time>

The time the status last changed. Absent when the server has no reading, and while the console cannot reach the mesh.

statusstringrequired
Allowed:healthywarningerrorunknown
hoststringrequired
idstringrequired
in_usebooleanrequired
livesync_sessionsServerLivesyncResponse[]required
Show properties
Array of ServerLivesyncResponse
idstringrequired
namestringrequired
namestringrequired
overlay_ipstringrequired
portinteger<int64>required
reachableboolean

True when the fresh reachability note of the server says that the console reaches it over the mesh, false when it says not. Absent when there is no fresh note, and while the console cannot reach the mesh. The mesh status reads the same note.

rebuild_pendingbooleanrequired
retry_cleanup_refusalstring
slotsServerSlotResponse[]required
Show properties
Array of ServerSlotResponse
kindstringrequired
Allowed:database_servicedcs_cluster
member_namestringrequired
owner_namestringrequired
ssh_userstringrequired
statestringrequired
Allowed:in_usefreeneeds_cleanup
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/servers' \
  -H 'Cookie: tse_session=YOUR_API_KEY' \
  -H 'Accept: application/json'
Response
[
  {
    "cleaning_up": true,
    "cleanup_error": "string",
    "cleanup_kind": "deploy_refusal",
    "cleanup_pending": true,
    "cleanup_since": "string",
    "created_at": "string",
    "database_services": [
      {
        "database_service_id": "string",
        "database_service_name": "string",
        "role": "string"
      }
    ],
    "demo": true,
    "enroll_state": "pending",
    "headscale_node_id": "string",
    "health": {
      "checked_at": "2019-08-24T14:15:22Z",
      "notes": [
        {
          "cause": "unreachable",
          "component": "reachability",
          "message": "string",
          "since": "2019-08-24T14:15:22Z",
          "status": "healthy"
        }
      ],
      "reason": "string",
      "since": "2019-08-24T14:15:22Z",
      "status": "healthy"
    },
    "host": "string",
    "id": "string",
    "in_use": true,
    "livesync_sessions": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "name": "string",
    "overlay_ip": "string",
    "port": 0,
    "reachable": true,
    "rebuild_pending": true,
    "retry_cleanup_refusal": "string",
    "slots": [
      {
        "kind": "database_service",
        "member_name": "string",
        "owner_name": "string"
      }
    ],
    "ssh_user": "string",
    "state": "in_use"
  }
]