---
title: "GET | List a remote session by [id]"
slug: "api-v2-get-list-a-remote-session"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-get-list-a-remote-session"
---

> ## 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 a remote session by [id]

## Description

Access the full canonical record of one remote session in PAM Core, using the v2 model. The response returns the complete `SessionV2` entity, including fields that the listing endpoint omits. It also returns the conditional namespaces that describe a remote application or a remote device, when the session involves one.

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 a remote session by [id]](/v4-2/docs/api-get-list-a-remote-session).

---

## Prerequisites

- 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).
- The identification code of the session, returned by [GET | List all remote sessions](/v4-2/docs/api-v2-get-list-all-remote-sessions).

              Attention

              

This endpoint returns any remote session 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/{id}`

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Unique identification code of the session. **Note:** this is the `id` field returned by [GET \| List all remote sessions](/v4-2/docs/api-v2-get-list-all-remote-sessions), not the `session.session_id` value. |

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | string | No | 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/810`

---

## Response

```
HTTP/1.1 200 OK
```

### Example response body

```
{
    "data": {
        "id": "810",
        "session": {
            "session_id": "S2026083010100",
            "session_type": "rdp_proxy",
            "protocol": "RDP",
            "port": 3389,
            "status": "active",
            "user": "jsilva",
            "justification": "Quarterly reconciliation in the ERP",
            "access_period": "2026-08-30T10:00:00+00:00/2026-08-30T12:00:00+00:00",
            "origin": "200.100.50.51",
            "selection_mode": "explicit",
            "created_at": "2026-08-30T10:10:00+00:00",
            "started_at": "2026-08-30T10:10:05+00:00",
            "ended_at": null,
            "duration": "00:02:41"
        },
        "device": {
            "id": 61,
            "hostname": "rds-01"
        },
        "credential": {
            "id": 101,
            "username": "svc-payments"
        },
        "remote_app": {
            "id": 12,
            "name": "ERP Access"
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/pam/sessions/810"
        }
    }
}
```

### Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The session record. |
| `meta` | object | Navigation links. Carries `links.self` only. |

#### `data`

| Field | Type | Description |
| --- | --- | --- |
| →`id` | string | Unique identification code of the 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. |
| →`remote_device` | object | Device the credential belongs to, returned only when it differs from the session device. This happens with domain credentials. Omitted when it does not apply and never returned as `null`. Check whether the key is present. |
| →`remote_app` | object | Remote application published in the session, returned only for RemoteApp sessions. Omitted when it does not apply and never returned as `null`. Check whether the key is present. |

#### `data.session`

| Field | Type | Description |
| --- | --- | --- |
| →→`session_id` | string | Session identifier shown to users and referenced in incident tickets. |
| →→`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`. |
| →→`port` | integer | Port used by the session on the target device. Returned by this endpoint only. |
| →→`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-30T10:10:00+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. |

#### `data.remote_device`

| Field | Type | Description |
| --- | --- | --- |
| →→`id` | integer | Unique identification code of the device the credential belongs to. |
| →→`hostname` | string | Hostname of that device. |

#### `data.remote_app`

| Field | Type | Description |
| --- | --- | --- |
| →→`id` | integer | Unique identification code of the remote application. |
| →→`name` | string | Name of the remote application published in the session. |

              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 |
| --- | --- | --- | --- |
| `401` | `api.auth.token.invalid` | Missing, expired or invalid bearer token. | Request a new access token. |
| `404` | `api.resource.not_found` | No session exists with the identification code sent in the request path. | Check the `id` against [GET \| List all remote sessions](/v4-2/docs/api-v2-get-list-all-remote-sessions). |
| `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` | The `id` in the request path is not a positive integer. | Send the numeric identification code of the session. |
| `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 all remote sessions](/v4-2/docs/api-v2-get-list-all-remote-sessions)
- [GET | List a remote session by [id]](/v4-2/docs/api-get-list-a-remote-session)
- [How to manage authorizations in A2A for API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)