GET | List all remote sessions

Description

List the remote sessions recorded in PAM Core, using the v2 canonical model. Returns a paginated, filterable projection of the SessionV2 entity. Use it for audit reviews, SOC monitoring, and incremental SIEM synchronization.

This endpoint is read-only. Creating and closing sessions is not part of the v2 surface.

Info

This endpoint is part of the A2A API v2 surface, introduced in version 4.2.13. The v1 equivalent is documented in GET | List all remote sessions.

Prerequisites

This endpoint requires an A2A application with API access and a valid OAuth2 token. For more information, access How to manage authorizations in A2A for API v2.

Attention

This endpoint returns all remote sessions in the environment. It does not filter results by the credential grants of the calling application, which matches the behavior of the v1 remote-session endpoints. This may change in a future version.

Request

GET /api/v2/pam/sessions

Query parameters

All query parameters are optional. When no parameters are provided, the endpoint returns the most recent sessions using the default sort and page size.

Filter names are qualified with the namespace they belong to, such as session.status or device.id. Unqualified names return 400.

Filters

Field	Type	Description
`session.status`	string	Filters by session status. Allowed values: `pending`, `active`, `terminated`, `expired`. Comma-separated values apply OR logic.
`session.session_type`	string	Filters by session type. Allowed values: `web_proxy`, `terminal_proxy`, `rdp_proxy`, `database_proxy`, `segura_browser`, `tcp_tunneling`, `epm`. Comma-separated values apply OR logic.
`session.selection_mode`	string	Filters by how the credential was chosen. Allowed values: `explicit`, `automatic`.
`session.protocol`	string	Filters by exact protocol match, such as `SSH`, `RDP` or `HTTPS`.
`session.user`	string	Filters by exact username of the user who requested the session.
`session.origin`	string	Filters by exact source IP address.
`session.created_at_gte`	string	Returns sessions created at or after this instant, in ISO 8601 format. Inclusive.
`session.created_at_lte`	string	Returns sessions created at or before this instant, in ISO 8601 format. Inclusive.
`device.id`	integer	Filters by exact device ID.
`credential.id`	integer	Filters by exact credential ID. Matches the effective credential, which is the automation macro credential when one is present, and the direct credential otherwise.

An invalid enum value returns 422 api.enum.invalid_value. A session.created_at_gte later than session.created_at_lte returns 422 api.validation.invalid_date_range.

For full filter validation rules and AND/OR logic, see API v2 - Conventions and shared behaviors.

Search

Field	Type	Description
`search`	string	Substring search across the session identifier, the device hostname and the credential username. Minimum three characters.

Unlike the filters, search is not namespaced. Sending session.search returns 400, and a term shorter than three characters returns 400 api.request.bad_request.

Sorting

Field	Type	Description
`sort_by`	string	One or more fields in the format `field:asc` or `field:desc`, comma-separated and processed left to right. Default: `session.created_at:desc`.

Sortable fields are session.created_at, session.started_at and session.ended_at. An unknown field returns 422 api.sort.invalid_field, and a direction other than asc or desc returns 422 api.sort.invalid_direction.

Results carry a unique internal tiebreaker in the same direction as the sort. This keeps pagination stable when new sessions are created while you page through the results.

Pagination

Field	Type	Description
`page`	integer	Page number, starting at `1`. Default: `1`.
`limit`	integer	Results per page. Minimum `1`, maximum `200`. Default: `50`.

A limit greater than 200 returns 422 api.pagination.limit.exceeded.

To synchronize sessions incrementally, set a floor with session.created_at_gte and follow meta.links.next until the field is absent from the response. Do not iterate until meta.pagination.total_pages: the totals are informative, and meta.links.next is the supported way to advance.

For full pagination rules, see API v2 - Conventions and shared behaviors.

Field projection

Field	Type	Description
`fields`	string	Comma-separated canonical keys to return, such as `session.status,device.hostname`. The `id` field is always returned.

An unknown key returns 422 api.validation.invalid_field. For the full projection rules, see API v2 - Conventions and shared behaviors.

Example request

GET {{url}}/api/v2/pam/sessions?session.status=active&limit=50

Response

HTTP/1.1 200 OK

A filter that matches nothing returns 200 with an empty data array, not an error.

Example response body

{
    "data": [
        {
            "id": "789",
            "session": {
                "session_id": "S2026082912345",
                "session_type": "terminal_proxy",
                "protocol": "SSH",
                "status": "active",
                "user": "dalmeida",
                "justification": "Maintenance window MW-2026-0829",
                "access_period": null,
                "origin": "200.100.50.25",
                "selection_mode": "explicit",
                "created_at": "2026-08-29T12:34:56+00:00",
                "started_at": "2026-08-29T12:35:02+00:00",
                "ended_at": null,
                "duration": "00:15:32"
            },
            "device": {
                "id": 55,
                "hostname": "db-prod-01"
            },
            "credential": {
                "id": 101,
                "username": "svc-payments"
            }
        },
        {
            "id": "788",
            "session": {
                "session_id": "S2026082911980",
                "session_type": "epm",
                "protocol": null,
                "status": "terminated",
                "user": "jsilva",
                "justification": null,
                "access_period": "2026-08-29T09:00:00+00:00/2026-08-29T11:00:00+00:00",
                "origin": "200.100.50.51",
                "selection_mode": "automatic",
                "created_at": "2026-08-29T09:58:10+00:00",
                "started_at": "2026-08-29T10:01:44+00:00",
                "ended_at": "2026-08-29T10:29:12+00:00",
                "duration": "00:27:28"
            },
            "device": {
                "id": 61,
                "hostname": "ws-finance-04"
            },
            "credential": null
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "limit": 50,
            "total_items": 1250,
            "total_pages": 25
        },
        "links": {
            "self": "/api/v2/pam/sessions?session.status=active&page=1&limit=50",
            "next": "/api/v2/pam/sessions?session.status=active&page=2&limit=50"
        }
    }
}

Response body fields

Field	Type	Description
`data`	array of objects	Sessions matching the request.
`meta`	object	Pagination metadata and navigation links.

`data`

Field	Type	Description
→`id`	string	Unique identification code of the session. Use this value in the request path of GET \| List a remote session by [id].
→`session`	object	Session attributes.
→`device`	object	Device the session connected to.
→`credential`	object	Credential used by the session. `null` for ad-hoc and EPM sessions that do not use a vault credential.

`data.session`

Field	Type	Description
→→`session_id`	string	Session identifier shown to users and referenced in incident tickets. This is the value the `search` parameter matches.
→→`session_type`	string	Type of session. One of `web_proxy`, `terminal_proxy`, `rdp_proxy`, `database_proxy`, `segura_browser`, `tcp_tunneling`, `epm`.
→→`protocol`	string	Protocol used by the session, such as `SSH`, `RDP` or `HTTPS`.
→→`status`	string	Current session status: `pending`, `active`, `terminated` or `expired`. Derived from the session timestamps rather than stored.
→→`user`	string	Username of the user who requested the session.
→→`justification`	string	Justification the user provided when requesting the session.
→→`access_period`	string	Approved access window as an ISO 8601 interval in the format `start/end`. `null` when the session has no approved request.
→→`origin`	string	Source IP address of the user who requested the session. This is personal data and is returned in full for audit purposes.
→→`selection_mode`	string	How the credential was chosen: `explicit` when the caller or the interface selected it, `automatic` when the system resolved it.
→→`created_at`	string	Date and time the session was requested, in ISO 8601 format and UTC. Example: `2026-08-29T12:34:56+00:00`.
→→`started_at`	string	Date and time the session started, in ISO 8601 format and UTC. `null` while the session is pending and for reservations that expired without starting.
→→`ended_at`	string	Date and time the session ended, in ISO 8601 format and UTC. For `expired` sessions, this is the instant the reservation expired. `null` while the session is active or pending.
→→`duration`	string	Elapsed session time in the format `HH:MM:SS`. Counts up while the session is active, holds the final value once the session ends, and is `null` when the session never started.

`data.device`

Field	Type	Description
→→`id`	integer	Unique identification code of the device.
→→`hostname`	string	Hostname of the device.

`data.credential`

Field	Type	Description
→→`id`	integer	Unique identification code of the credential.
→→`username`	string	Username of the credential used by the session. The secret value is never returned.

`meta`

Field	Type	Description
→`pagination`	object	Page number, page size and result totals.
→`links`	object	Navigation links. `self` is always present. `next` is present until the last page, and its absence signals the end of the result set.

Attention

The session access URL is never returned by this endpoint. Session URLs are single-use and are already expired for reading purposes. The credential is always returned, because which credential was used is audit data.

Errors

HTTP code	Error code	Possible cause	Solution
`400`	`api.request.bad_request`	Unknown query parameter, an unqualified filter name such as `status` instead of `session.status`, or a `search` term shorter than three characters.	Qualify the filter name with its namespace and check the parameter spelling.
`401`	`api.auth.token.invalid`	Missing, expired or invalid bearer token.	Request a new access token.
`422`	`api.enum.invalid_value`	Invalid value for `session.status`, `session.session_type` or `session.selection_mode`.	Send one of the allowed values listed in the Filters table.
`422`	`api.validation.invalid_date_range`	`session.created_at_gte` is later than `session.created_at_lte`.	Correct the date range.
`422`	`api.pagination.limit.exceeded`	`limit` is greater than `200`.	Send a `limit` of `200` or lower.
`422`	`api.sort.invalid_field`	`sort_by` references a field outside the sortable set.	Sort by `session.created_at`, `session.started_at` or `session.ended_at`.
`422`	`api.sort.invalid_direction`	`sort_by` uses a direction other than `asc` or `desc`.	Use `asc` or `desc`.
`422`	`api.validation.invalid_field`	`fields` references an unknown canonical key.	Check the key names against the Response body fields tables.
`422`	`api.request.invalid_param`	A parameter has the wrong type, such as a non-integer `device.id` or an unparseable date.	Correct the parameter type.
`429`	`rate_limit_exceeded`	The request budget for the current window is exhausted.	Wait the number of seconds given in the `Retry-After` header, then retry.
`500`	`api.internal.error`	Internal server error.	Contact the Segura™ support team.

For authentication error messages and the 403 versus 404 policy, see API v2 - Conventions and shared behaviors.