---
title: "GET | List all remote sessions"
slug: "api-v2-get-list-all-remote-sessions"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-get-list-all-remote-sessions"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v4-2/docs/api-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](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).

              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](/v4-2/docs/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](/v4-2/docs/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](/v4-2/docs/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]](/v4-2/docs/api-v2-get-list-a-remote-session). |
| →`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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

---

## Related documents

- [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [GET | List a remote session by [id]](/v4-2/docs/api-v2-get-list-a-remote-session)
- [GET | List all remote sessions](/v4-2/docs/api-get-list-all-remote-sessions)
- [How to manage authorizations in A2A for API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)