This topic describes how to query the session list of a tenant by using an API. You can use the API to perform pagination, filtering, and sorting.
API call description
If a password is set, you must authenticate. For more information, see Hybrid encryption.
Request path
GET /api/v1/tenant/:name/sessions
Request parameters
Parameter |
Type |
Required |
Example value |
Description |
|---|---|---|---|---|
| name | string | Yes | t1 | The name of the tenant. This parameter is specified in the path. |
| page | uint64 | No | 1 | The page number. The default value is 1. This parameter is specified in the query parameter. |
| size | uint64 | No | 10 | The number of records per page. The default value is 2147483647. This parameter is specified in the query parameter. |
| user | string | No | root | The username of the database user. This parameter is specified in the query parameter. |
| db | string | No | test | The name of the database. This parameter is specified in the query parameter. |
| host | string | No | 10.10.10.1 | The IP address of the client host. This parameter is specified in the query parameter. |
| id | uint64 | No | 12345 | The session ID. This parameter is specified in the query parameter. |
| observer_list | string | No | 10.10.10.1,10.10.10.2 | The list of OBServer nodes. Separate multiple IP addresses with commas. This parameter is specified in the query parameter. |
| active_only | boolean | No | true | Specifies whether to query only active sessions. This parameter is specified in the query parameter. |
| sort | string | No | time,desc | The sorting parameter. The format is "field name,sort order" (for example, "time,desc"). This parameter is specified in the query parameter. |
Response
Parameter |
Type |
Description |
|---|---|---|
| successful | bool | Indicates whether the request was successful. |
| timestamp | time.Time | The timestamp when the server completed the request. |
| duration | int | The time taken by the server to process the request, in milliseconds. |
| status | int | The HTTP status code. |
| traceId | string | The Trace ID of the request. |
| data | PaginatedTenantSessions | The paginated session list. The data structure contains the following information:
|
| error | ApiError | The error information returned in the response. The data structure contains the following information:
|
Data structure of TenantSession:
Parameter |
Type |
Description |
|---|---|---|
| id | int64 | The session ID. |
| svr_ip | string | The IP address of the server. |
| svr_port | int64 | The port number of the server. |
| sql_port | int64 | The SQL port. |
| user | string | The username of the database user. |
| db | string | The name of the database. |
| tenant | string | The name of the tenant. |
| host | string | The IP address and port number of the client host. |
| command | string | The command being executed. |
| time | float64 | The duration of the session, in seconds. |
| state | string | The state of the session. For example, "ACTIVE". |
| info | string | The SQL statement being executed. |
| proxy_sess_id | int64 | The ID of the proxy session. |
| proxy_ip | string | The IP address of the proxy. This parameter is resolved from the host when the proxy session ID is not empty. |
| action | string | The action. |
| module | string | The module. |
| client_info | string | The client information. |
| level | int64 | The level. |
| sample_percentage | int | The sampling percentage. |
| record_policy | string | The record policy. |
| sql_id | string | The SQL ID. |
| total_cpu_time | int64 | The total CPU time. |
| memory_usage | int64 | The memory usage. |
Data structure of CustomPage:
Parameter |
Type |
Description |
|---|---|---|
| total_elements | uint64 | The total number of records. |
| total_pages | uint64 | The total number of pages. |
| size | uint64 | The number of records per page. |
| number | uint64 | The page number. |
Examples
Request example
GET 10.10.10.1:2886/api/v1/tenant/t1/sessions?page=1&size=10&active_only=true&sort=time,desc
Response example
{
"successful": true,
"timestamp": "2025-12-22T20:29:05.222993955+08:00",
"duration": 31,
"status": 200,
"traceId": "0b33bb5ae5a51aab",
"data": {
"page": {
"total_elements": 1,
"total_pages": 1,
"size": 10,
"number": 1
},
"contents": [
{
"id": 3221588508,
"svr_ip": "10.10.10.01",
"svr_port": 2882,
"sql_port": 2881,
"user": "root",
"db": "ocs",
"tenant": "t1",
"host": "127.0.0.1:26236",
"command": "Execute",
"time": 0.005242,
"state": "ACTIVE",
"info": "SELECT * FROM `oceanbase`.`GV$OB_PROCESSLIST` WHERE TENANT = ? AND STATE = 'ACTIVE' ORDER BY time desc LIMIT 10",
"proxy_sess_id": 0,
"proxy_ip": "",
"action": "",
"module": "",
"client_info": "",
"level": 1,
"sample_percentage": 10,
"record_policy": "SAMPLE_AND_SLOW_QUERY",
"sql_id": "C82D7414C2E9706348979FC0CE2199E9",
"total_cpu_time": 0,
"memory_usage": 3162112
}
]
}
}