Help Center/ Distributed Cache Service/ API Reference/ API V2/ Session Management/ Obtaining Session List
Updated on 2025-05-13 GMT+08:00
View PDF

Obtaining Session List

Function

This API is used to obtain the session list.

Calling Method

For details, see Calling APIs.

URI

GET /v2/{project_id}/instances/{instance_id}/clients

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details, see Obtaining a Project ID.

instance_id

Yes

String

Instance ID.
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

node_id

Yes

String

Node ID. For a read/write splitting or Proxy Cluster instance, use the node_id of a proxy. For a single-node, master/standby, or Redis Cluster instance, use the node_id of a data node.

offset

No

Integer

Offset, which is the position where the query starts. The value must be greater than or equal to 0. The default value is 0.

limit

No

Integer

Number of records displayed on each page. The minimum value is 1. The maximum value is 1000*. The default value is 10.

addr

No

String

Filter by client connection addresses.

sort

No

String

Sorting field, which specifies a value in the ClientInfo for sorting sessions.

order

No

String

Sorting mode. The options are asc (ascending order) and desc (descending order).

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

time

String

Data update time.

clients

Array of ClientInfo objects

Session list.

count

Integer

Total number of sessions.
Table 4 ClientInfo

Parameter

Type

Description

id

String

Client ID.

addr

String

IP address and port of the client.

fd

String

File descriptor used in containers.

name

String

Client name.

cmd

String

Last executed command.

age

Integer

Connection duration (s).

idle

Integer

Idle duration (s).

db

String

ID of the database used by the client.

flags

String

Client flag. By default, this parameter is not set and the value is N.

sub

Integer

Number of subscribed channels.

psub

Integer

Number of subscribed modes.

multi

Integer

Number of commands executed in a transaction.

qbuf

Integer

Querying buffer length, in bytes. 0: There is no buffer.

qbuf_free

Integer

Querying length of the remaining buffer, in bytes. 0: There is no remaining buffer.

obl

Integer

Length of output buffer, in bytes. 0: No output buffer is allocated.

oll

Integer

Number of objects contained in the output list (When the length of the remaining buffer is 0, responses to user commands are enqueued as a string object.)

omem

Integer

Total memory occupied by the output buffer and the output list.

events

String

File operations. r indicates read and w indicates write.

network

String

Type of the network used by the client.

peer

String

IP address and port of the client.

user

String

Client user.

Status code: 400

Table 5 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Status code: 401

Table 6 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Status code: 403

Table 7 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Status code: 404

Table 8 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Status code: 500

Table 9 Response body parameters

Parameter

Type

Description

error_msg

String

Error message.

error_code

String

Error code.

error_ext_msg

String

Error message details.

Example Requests

GET https://{dcs_endpoint}/v2/{project_id}/instances/{instance_id}/clients?node_id=8f7ee181-88e2-49b7-a4bf-81f18f93a135

Example Responses

Status code: 200

Successful.

{
  "time" : "2023-06-15T03:10:01.332Z",
  "clients" : [ {
    "id" : "11677",
    "addr" : "198.19.131.14:1637",
    "name" : "dcs",
    "cmd" : "info",
    "age" : 376,
    "idle" : 376,
    "flags" : "N",
    "fd" : "16",
    "db" : "0",
    "sub" : 0,
    "psub" : 0,
    "multi" : 1,
    "qbuf" : 0,
    "qbuf_free" : 4,
    "obl" : 0,
    "oll" : 0,
    "omem" : 0,
    "events" : "r",
    "network" : "vpc",
    "peer" : "198.198.0.121:4058",
    "user" : "dcs"
  } ],
  "count" : 1
}

Status code: 400

Invalid request.

{
  "error_code" : "DCS.4957",
  "error_msg" : "This operation is not allowed when the task is in the current state."
}

Status Codes

Status Code

Description

200

Successful.

400

Invalid request.

401

Invalid authentication information.

403

Access denied.

404

The requested resource could not be found.

500

Internal service error.

Error Codes

See Error Codes.

Parent topic: Session Management