> ## Documentation Index > Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List sessions > List all sessions on this cluster. If a username is provided, only sessions from that user are returned. Client must be logged in as a user with admin privileges. ## OpenAPI ````yaml /openapi/cluster-api-v2.json get /sessions/ openapi: 3.0.0 info: description: >- REST API for querying information about CockroachDB cluster health, nodes, ranges, sessions, and other meta information. For additional details, see cockroachlabs.com/docs/stable/cluster-api. title: CockroachDB v2 API license: name: Business Source License version: '2.0' x-logo: url: https://www.cockroachlabs.com/docs/images/cockroachlabs-logo-170.png backgroundColor: '#FFFFFF' altText: Cockroach Labs logo servers: - url: https://localhost/api/v2 - url: http://localhost/api/v2 security: [] paths: /sessions/: get: summary: List sessions description: |- List all sessions on this cluster. If a username is provided, only sessions from that user are returned. Client must be logged in as a user with admin privileges. operationId: listSessions parameters: - description: >- Username of user to return sessions for; if unspecified, sessions from all users are returned. name: username in: query schema: type: string - description: Maximum number of results to return in this call. name: limit in: query schema: type: integer - description: Continuation token for results after a past limited run. name: start in: query schema: type: string responses: '200': description: List sessions response. content: application/json: schema: $ref: '#/components/schemas/listSessionsResp' security: - api_session: [] x-codeSamples: - lang: Shell + Curl source: |- curl --request GET \ --url 'https://localhost/api/v2/sessions/?username=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&start=SOME_STRING_VALUE' \ --header 'X-Cockroach-API-Session: REPLACE_KEY_VALUE' components: schemas: listSessionsResp: type: object title: Response for listSessions. properties: errors: description: Any errors that occurred during fan-out calls to other nodes. type: array items: $ref: '#/components/schemas/ListSessionsError' x-go-name: Errors next: description: >- The continuation token, for use in the next paginated call in the `start` parameter. type: string x-go-name: Next sessions: description: A list of sessions on this node or cluster. type: array items: $ref: '#/components/schemas/Session' x-go-name: Sessions x-go-name: listSessionsResponse x-go-package: github.com/cockroachdb/cockroach/pkg/server ListSessionsError: type: object title: An error wrapper object for ListSessionsResponse. properties: message: description: Error message. type: string x-go-name: Message node_id: $ref: '#/components/schemas/NodeID' x-go-package: github.com/cockroachdb/cockroach/pkg/server/serverpb Session: type: object title: Session represents one SQL session. properties: active_queries: description: Queries in progress on this session. type: array items: $ref: '#/components/schemas/ActiveQuery' x-go-name: ActiveQueries active_txn: $ref: '#/components/schemas/TxnInfo' alloc_bytes: description: Number of currently allocated bytes in the session memory monitor. type: integer format: int64 x-go-name: AllocBytes application_name: description: Application name specified by the client. type: string x-go-name: ApplicationName client_address: description: Connected client's IP address and port. type: string x-go-name: ClientAddress id: description: ID of the session (uint128 represented as raw bytes). type: array items: type: integer format: uint8 x-go-name: ID last_active_query: description: SQL string of the last query executed on this session. type: string x-go-name: LastActiveQuery last_active_query_no_constants: description: >- SQL statement fingerprint of the last query executed on this session, compatible with StatementStatisticsKey. type: string x-go-name: LastActiveQueryNoConstants max_alloc_bytes: description: High water mark of allocated bytes in the session memory monitor. type: integer format: int64 x-go-name: MaxAllocBytes node_id: $ref: '#/components/schemas/NodeID' start: description: Timestamp of session's start. type: string format: date-time x-go-name: Start username: description: Username of the user for this session. type: string x-go-name: Username x-go-package: github.com/cockroachdb/cockroach/pkg/server/serverpb NodeID: description: |- A custom type for a cockroach node ID. (not a raft node ID) 0 is not a valid NodeID. type: integer format: int32 x-go-package: github.com/cockroachdb/cockroach/pkg/roachpb ActiveQuery: type: object title: A query in flight on a session. properties: id: description: ID of the query (uint128 presented as a hexadecimal string). type: string x-go-name: ID is_distributed: description: True if this query is distributed. type: boolean x-go-name: IsDistributed phase: $ref: '#/components/schemas/ActiveQuery_Phase' progress: description: |- An estimate of the fraction of this query that has been processed. type: number format: float x-go-name: Progress sql: description: SQL query string specified by the user. type: string x-go-name: Sql sql_no_constants: description: >- The SQL statement fingerprint, compatible with StatementStatisticsKey. type: string x-go-name: SqlNoConstants start: description: Start timestamp of this query. type: string format: date-time x-go-name: Start txn_id: $ref: '#/components/schemas/UUID' x-go-package: github.com/cockroachdb/cockroach/pkg/server/serverpb TxnInfo: type: object title: >- Represents an in-flight user transaction on a session. This is for internal Cockroach Labs use. properties: alloc_bytes: description: >- Number of currently allocated bytes in the transaction memory monitor. type: integer format: int64 x-go-name: AllocBytes deadline: description: The deadline by which the transaction must be committed. type: string format: date-time x-go-name: Deadline id: $ref: '#/components/schemas/UUID' implicit: description: >- Implicit is true if this transaction was an implicit SQL transaction. type: boolean x-go-name: Implicit is_historical: type: boolean x-go-name: IsHistorical max_alloc_bytes: description: High water mark of allocated bytes in the txn memory monitor. type: integer format: int64 x-go-name: MaxAllocBytes num_auto_retries: description: |- The number of times that this transaction was automatically retried by the SQL executor. type: integer format: int32 x-go-name: NumAutoRetries num_retries: description: The number of times that this transaction was retried. type: integer format: int32 x-go-name: NumRetries num_statements_executed: description: |- The number of statements that were executed so far on this transaction. type: integer format: int32 x-go-name: NumStatementsExecuted priority: type: string x-go-name: Priority read_only: type: boolean x-go-name: ReadOnly start: description: The start timestamp of the transaction. type: string format: date-time x-go-name: Start txn_description: description: |- A text description of the underlying kv.Txn, intended for troubleshooting purposes. type: string x-go-name: TxnDescription x-go-package: github.com/cockroachdb/cockroach/pkg/server/serverpb ActiveQuery_Phase: type: integer format: int32 title: >- Phase of execution: `0` for PREPARING, `1` for EXECUTING. For more information see the doc "SHOW QUERIES". x-go-package: github.com/cockroachdb/cockroach/pkg/server/serverpb UUID: type: array title: An array type to represent the value of a UUID, as defined in RFC-4122. items: type: integer format: uint8 x-go-package: github.com/cockroachdb/cockroach/pkg/util/uuid securitySchemes: api_session: description: >- Token for logged-in REST session. Use `/login/` to log in and get a session token. For additional information, see cockroachlabs.com/docs/stable/cluster-api. type: apiKey name: X-Cockroach-API-Session in: header ````