Yugabyte cluster-info API
APIs for getting information about an existing cluster
APIs for getting information about an existing cluster
openapi: 3.0.0
info:
contact:
email: support@yugabyte.com
name: Yugabyte Cloud Support
url: https://support.yugabyte.com/
description: YugabyteDB as a Service
license:
name: Properietary (TBD)
url: https://www.yugabyte.com/yugabyte-cloud-terms-of-service
termsOfService: https://www.yugabyte.com/yugabyte-cloud-terms-of-service
title: Yugabyte Cloud backup-info cluster-info API
version: v1
servers:
- description: Endpoint of the API server
url: '{protocol}://{host_port}/api'
variables:
protocol:
default: http
enum:
- http
- https
host_port:
default: localhost:1323
security:
- BearerAuthToken: []
tags:
- description: APIs for getting information about an existing cluster
name: cluster-info
paths:
/live_queries:
get:
description: Get the Live Queries in a Yugabyte Cluster
operationId: getLiveQueries
parameters:
- description: type of queries for which to retrieve Live Queries (YSQL or YCQL)
explode: false
in: query
name: api
required: false
schema:
enum:
- YSQL
- YCQL
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/LiveQueryResponseSchema'
description: Live Queries of a Cluster
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get the live queries in a cluster
tags:
- cluster-info
/slow_queries:
get:
description: Get the Slow Queries in a Yugabyte Cluster
operationId: getSlowQueries
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SlowQueryResponseSchema'
description: Slow Queries of a Cluster
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get the slow queries in a cluster
tags:
- cluster-info
/nodes:
get:
description: Get nodes for a Yugabyte cluster
operationId: getClusterNodes
parameters:
- allowEmptyValue: true
description: Whether to get master-only nodes that have no tserver
explode: true
in: query
name: get_all_masters
required: false
schema:
type: boolean
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Cluster_Nodes_Response'
description: Cluster nodes response
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get the nodes for a cluster
tags:
- cluster-info
/metrics:
get:
description: Get metrics for a Yugabyte cluster
operationId: getClusterMetric
parameters:
- description: Which metrics to retrieve results for
explode: false
in: query
name: metrics
required: true
schema:
type: string
style: form
- description: Node name within the cluster
explode: false
in: query
name: node_name
required: false
schema:
type: string
style: form
- description: Region name to filter for the given cluster
explode: false
in: query
name: region
required: false
schema:
type: string
style: form
- description: Zone to filter for the given cluster
explode: false
in: query
name: zone
required: false
schema:
type: string
style: form
- description: Start of range of time series data (in epoch seconds)
explode: false
in: query
name: start_time
required: false
schema:
format: int64
minimum: 0
type: integer
style: form
- description: End of range of time series data (in epoch seconds)
explode: false
in: query
name: end_time
required: false
schema:
format: int64
minimum: 0
type: integer
style: form
- description: Cluster type (primary or read replica)
explode: false
in: query
name: cluster_type
required: false
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Metric_Response'
description: Metric response
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get a metric for a cluster
tags:
- cluster-info
/activities:
get:
description: Get activities data for a Yugabyte cluster
operationId: getClusterActivities
parameters:
- description: Which activities data to retrieve
explode: false
in: query
name: activities
required: true
schema:
type: string
style: form
- description: Completed or In-Progress
explode: false
in: query
name: status
required: true
schema:
type: string
style: form
- description: Which database's activities data is to be retrived.
explode: false
in: query
name: database
required: false
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Activities_Response'
description: Activities Response
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get a activities data for a cluster
tags:
- cluster-info
/tables:
get:
description: Get list of tables per YB API (YCQL/YSQL)
operationId: getClusterTables
parameters:
- description: Which DB API to get tables for (YCQL/YSQL)
explode: false
in: query
name: api
required: false
schema:
enum:
- YCQL
- YSQL
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Cluster_table_list_response'
description: List of cluster tables
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get list of DB tables per YB API (YCQL/YSQL)
tags:
- cluster-info
/table:
get:
description: Get info on a single table, given table uuid
operationId: getTableInfo
parameters:
- description: UUID of the table
explode: false
in: query
name: id
required: true
schema:
type: string
style: form
- description: Specify the node ip-address from where the table info is retrieved
explode: false
in: query
name: node_address
required: true
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TableInfo'
description: Information for a single table
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get info on a single table, given table uuid
tags:
- cluster-info
/health-check:
get:
description: Get health information about the cluster
operationId: getClusterHealthCheck
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Health_Check_Response'
description: Successful health check response
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get health information about the cluster
tags:
- cluster-info
/tablets:
get:
description: Get list of tablets
operationId: getClusterTablets
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Cluster_tablet_list_response'
description: List of cluster tablets
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get list of tablets
tags:
- cluster-info
/version:
get:
description: Get YugabyteDB version
operationId: getVersion
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VersionInfo'
description: Version info for YugabyteDB
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get YugabyteDB version
tags:
- cluster-info
/is_load_balancer_idle:
get:
description: Check if cluster load balancer is idle
operationId: getIsLoadBalancerIdle
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Is_load_balancer_idle'
description: Is load balancer idle
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Check if cluster load balancer is idle
tags:
- cluster-info
/gflags:
get:
description: Retrieve gflags of master and tserver process
operationId: getGflags
parameters:
- description: Specify the node ip-address from where alerts are retrieved
explode: false
in: query
name: node_address
required: true
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GflagsInfo'
description: Gflags information
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get gflags of master and tserver process
tags:
- cluster-info
/alerts:
get:
description: Get any alerts for the cluster
operationId: getClusterAlerts
parameters:
- description: Specify the node ip-address from where gflags are retrieved
explode: false
in: query
name: node_address
required: true
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Alerts_Response'
description: Alerts information
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get any alerts for the cluster
tags:
- cluster-info
/connections:
get:
description: Get YSQL connection manager stats for every node of the cluster
operationId: getClusterConnections
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionsStats'
description: YSQL connection manager stats
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get YSQL connection manager stats for every node of the cluster
tags:
- cluster-info
/node_address:
get:
description: Get the node address for the current node
operationId: getNodeAddress
responses:
'200':
content:
text/plain:
schema:
type: string
description: Node address
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
description: API Error
summary: Get the node address for the current node
tags:
- cluster-info
components:
schemas:
ColumnInfo:
description: Column Info
example:
column: column
id: id
type: type
properties:
column:
type: string
id:
type: string
type:
type: string
title: Column Info
type: object
TableInfo:
description: Table Info
example:
table_tablespace_oid: table_tablespace_oid
table_replication_info:
live_replicas:
placement_uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
num_replicas: 6
placement_blocks:
- cloud_info:
placement_region: placement_region
placement_zone: placement_zone
placement_cloud: placement_cloud
min_num_replicas: 1
- cloud_info:
placement_region: placement_region
placement_zone: placement_zone
placement_cloud: placement_cloud
min_num_replicas: 1
read_replicas:
- placement_uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
num_replicas: 6
placement_blocks:
- cloud_info:
placement_region: placement_region
placement_zone: placement_zone
placement_cloud: placement_cloud
min_num_replicas: 1
- cloud_info:
placement_region: placement_region
placement_zone: placement_zone
placement_cloud: placement_cloud
min_num_replicas: 1
- placement_uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
num_replicas: 6
placement_blocks:
- cloud_info:
placement_region: placement_region
placement_zone: placement_zone
placement_cloud: placement_cloud
min_num_replicas: 1
- cloud_info:
placement_region: placement_region
placement_zone: placement_zone
placement_cloud: placement_cloud
min_num_replicas: 1
table_state: table_state
table_state_message: table_state_message
columns:
- column: column
id: id
type: type
- column: column
id: id
type: type
table_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
table_version: 0
table_name: table_name
tablets:
- tablet_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
partition: partition
raft_config:
- role: role
location: location
uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
- role: role
location: location
uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
hidden: true
split_depth: 5
state: state
message: message
- tablet_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
partition: partition
raft_config:
- role: role
location: location
uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
- role: role
location: location
uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
hidden: true
split_depth: 5
state: state
message: message
table_type: table_type
properties:
table_name:
type: string
table_id:
format: uuid
type: string
table_version:
type: integer
table_type:
type: string
table_state:
type: string
table_state_message:
type: string
table_tablespace_oid:
type: string
table_replication_info:
$ref: '#/components/schemas/TableInfo_table_replication_info'
columns:
items:
$ref: '#/components/schemas/ColumnInfo'
type: array
tablets:
items:
$ref: '#/components/schemas/TabletInfo'
type: array
required:
- columns
- table_id
- table_name
- table_replication_info
- table_state
- table_state_message
- table_type
- table_version
- tablets
title: Table Info
type: object
Gflag:
description: Gflag
example:
name: name
type: type
value: value
properties:
name:
type: string
value:
type: string
type:
type: string
title: Gflag
type: object
Alerts_Response:
example:
data:
- name: name
info: info
- name: name
info: info
properties:
data:
items:
$ref: '#/components/schemas/AlertsInfo'
type: array
required:
- data
title: Alerts Response
type: object
SlowQueryResponseYSQLQueryItem:
description: Schema for Slow Query Response YSQL Query Item
example:
query: query
datname: datname
local_blks_written: 5
rows: 3
stddev_time: 2.027123023002322
min_time: 9.301444243932576
queryid: 6
rolname: rolname
local_blks_hit: 5
calls: 1
max_time: 2.3021358869347655
mean_time: 7.061401241503109
total_time: 4.145608029883936
properties:
queryid:
format: int64
type: integer
query:
type: string
rolname:
type: string
datname:
type: string
calls:
type: integer
local_blks_hit:
type: integer
local_blks_written:
type: integer
max_time:
format: double
type: number
mean_time:
format: double
type: number
min_time:
format: double
type: number
rows:
type: integer
stddev_time:
format: double
type: number
total_time:
format: double
type: number
title: Slow Query Response YSQL Query Item
type: object
ClusterTablet:
description: Model representing a tablet
example:
tablet_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
namespace: namespace
table_uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
table_name: table_name
has_leader: true
properties:
namespace:
type: string
table_name:
type: string
table_uuid:
format: uuid
type: string
tablet_id:
format: uuid
type: string
has_leader:
type: boolean
required:
- has_leader
- namespace
- table_id
- table_name
- table_uuid
title: Cluster Tablet Object
type: object
SlowQueryResponseYSQLData:
description: Schema for Slow Query Response YSQL Data
example:
error_count: 0
queries:
- query: query
datname: datname
local_blks_written: 5
rows: 3
stddev_time: 2.027123023002322
min_time: 9.301444243932576
queryid: 6
rolname: rolname
local_blks_hit: 5
calls: 1
max_time: 2.3021358869347655
mean_time: 7.061401241503109
total_time: 4.145608029883936
- query: query
datname: datname
local_blks_written: 5
rows: 3
stddev_time: 2.027123023002322
min_time: 9.301444243932576
queryid: 6
rolname: rolname
local_blks_hit: 5
calls: 1
max_time: 2.3021358869347655
mean_time: 7.061401241503109
total_time: 4.145608029883936
properties:
error_count:
description: Count of Errors
type: integer
queries:
items:
$ref: '#/components/schemas/SlowQueryResponseYSQLQueryItem'
type: array
title: Slow Query Response YSQL Data
type: object
Is_load_balancer_idle:
description: Is load balancer idle
example:
is_idle: true
properties:
is_idle:
type: boolean
required:
- is_idle
title: Is load balancer idle
type: object
PlacementCloudInfo:
description: Placement Cloud Info
example:
placement_region: placement_region
placement_zone: placement_zone
placement_cloud: placement_cloud
properties:
placement_cloud:
type: string
placement_region:
type: string
placement_zone:
type: string
title: Placement Cloud Info
type: object
ConnectionStatsItem:
properties:
database_name:
type: string
user_name:
type: string
active_logical_connections:
format: int64
type: integer
queued_logical_connections:
format: int64
type: integer
waiting_logical_connections:
format: int64
type: integer
active_physical_connections:
format: int64
type: integer
idle_physical_connections:
format: int64
type: integer
avg_wait_time_ns:
format: int64
type: integer
qps:
format: int64
type: integer
tps:
format: int64
type: integer
required:
- active_logical_connections
- active_physical_connections
- avg_wait_time_ns
- idle_physical_connections
- qps
- queued_logical_connections
- tps
- waiting_logical_connections
type: object
NodeData_cloud_info:
example:
cloud: cloud
zone: zone
region: region
properties:
cloud:
type: string
region:
type: string
zone:
type: string
required:
- region
- zone
type: object
Metric_Response:
example:
data:
- values:
- - 0.8008281904610115
- 0.8008281904610115
- - 0.8008281904610115
- 0.8008281904610115
name: name
- values:
- - 0.8008281904610115
- 0.8008281904610115
- - 0.8008281904610115
- 0.8008281904610115
name: name
end_timestamp: 1
start_timestamp: 6
properties:
data:
items:
$ref: '#/components/schemas/MetricData'
type: array
start_timestamp:
description: Start of range of results
format: int64
type: integer
end_timestamp:
description: End of range of results
format: int64
type: integer
required:
- data
- end_timestamp
- start_timestamp
title: Metric Response
type: object
PlacementBlock:
description: Placement Block
example:
cloud_info:
placement_region: placement_region
placement_zone: placement_zone
placement_cloud: placement_cloud
min_num_replicas: 1
properties:
cloud_info:
$ref: '#/components/schemas/PlacementCloudInfo'
min_num_replicas:
type: integer
title: Placement Block
type: object
NodeData_metrics_active_connections:
example:
ysql: 0
ycql: 0
properties:
ysql:
default: 0
format: int64
minimum: 0
type: integer
ycql:
default: 0
format: int64
minimum: 0
type: integer
required:
- ycql
- ysql
type: object
YbApiEnum:
description: Type of DB API (YSQL/YCQL)
enum:
- YSQL
- YCQL
title: Yb Api Enum
type: string
TabletInfo:
description: Tablet Info
example:
tablet_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
partition: partition
raft_config:
- role: role
location: location
uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
- role: role
location: location
uuid: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
hidden: true
split_depth: 5
state: state
message: message
properties:
tablet_id:
format: uuid
type: string
partition:
type: string
split_depth:
type: integer
state:
type: string
hidden:
type: boolean
message:
type: string
raft_config:
items:
$ref: '#/components/schemas/RaftConfig'
type: array
title: Tablet Info
type: object
SlowQueryResponseData:
description: Slow Query Response Data
example:
ysql:
error_count: 0
queries:
- query: query
datname: datname
local_blks_written: 5
rows: 3
stddev_time: 2.027123023002322
min_time: 9.301444243932576
queryid: 6
rolname: rolname
local_blks_hit: 5
calls: 1
max_time: 2.3021358869347655
mean_time: 7.061401241503109
total_time: 4.145608029883936
- query: query
datname: datname
local_blks_written: 5
rows: 3
stddev_time: 2.027123023002322
min_time: 9.301444243932576
queryid: 6
rolname: rolname
local_blks_hit: 5
calls: 1
max_time: 2.3021358869347655
mean_time: 7.061401241503109
total_time: 4.145608029883936
properties:
ysql:
$ref: '#/components/schemas/SlowQueryResponseYSQLData'
title: Slow Query Response Data
type: object
Cluster_table_list_response:
example:
tables:
- keyspace: keyspace
size_bytes: 0
name: name
uuid: uuid
- keyspace: keyspace
size_bytes: 0
name: name
uuid: uuid
indexes:
- keyspace: keyspace
size_bytes: 0
name: name
uuid: uuid
- keyspace: keyspace
size_bytes: 0
name: name
uuid: uuid
properties:
tables:
description: List of cluster tables
items:
$ref: '#/components/schemas/ClusterTable'
nullable: false
title: Cluster Table Data
type: array
uniqueItems: true
indexes:
description: List of cluster tables
items:
$ref: '#/components/schemas/ClusterTable'
nullable: false
title: Cluster Table Data
type: array
uniqueItems: true
required:
- indexes
- tables
title: Cluster table list response
type: object
HealthCheckInfo:
example:
most_recent_uptime: 0
dead_nodes:
- 046b6c7f-0b8a-43b9-b35d-6489e6daee91
- 046b6c7f-0b8a-43b9-b35d-6489e6daee91
leaderless_tablets:
- 046b6c7f-0b8a-43b9-b35d-6489e6daee91
- 046b6c7f-0b8a-43b9-b35d-6489e6daee91
under_replicated_tablets:
- 046b6c7f-0b8a-43b9-b35d-6489e6daee91
- 046b6c7f-0b8a-43b9-b35d-6489e6daee91
properties:
dead_nodes:
description: UUIDs of dead nodes
items:
format: uuid
type: string
type: array
most_recent_uptime:
format: int64
minimum: 0
type: integer
under_replicated_tablets:
description: UUIDs of under-replicated tablets
items:
format: uuid
type: string
type: array
leaderless_tablets:
description: UUIDs of leaderless tablets
items:
format: uuid
type: string
type: array
required:
- dead_nodes
- leaderless_tablets
- most_recent_uptime
- under_replicated_tablets
title: Health Check Info
type: object
ApiError_error:
properties:
detail:
description: Error message
type: string
status:
description: Error code
type: integer
type: object
LiveQueryResponseSchema:
description: Live Query Response Schema
example:
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/yugabyte/refs/heads/main/openapi/yugabyte-cluster-info-api-openapi.yml