---
title: "GET | Listar todas as sessões remotas"
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 | Listar todas as sessões remotas

## Descrição

Liste as sessões remotas registradas no PAM Core, utilizando o modelo canônico v2. Retorna uma projeção paginada e filtrável da entidade `SessionV2`. Utilize-a para revisões de auditoria, monitoramento de SOC e sincronização incremental com SIEM.

Este endpoint é somente leitura. A criação e o encerramento de sessões não fazem parte da superfície v2.

              Info

              

Este endpoint faz parte da superfície da API v2 do A2A, introduzida na versão 4.2.13. O equivalente v1 está documentado em [GET | Listar todas as sessões remotas](/v4-2/docs/api-get-list-all-remote-sessions).

---

## Pré-requisitos

Este endpoint requer uma aplicação A2A com acesso à API e um token OAuth2 válido. Para mais informações, acesse [Como gerenciar autorizações no A2A para a API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).

              Atenção

              

Este endpoint retorna todas as sessões remotas do ambiente. Ele não filtra os resultados pelas concessões de credencial da aplicação chamadora, o que corresponde ao comportamento dos endpoints de sessão remota da v1. Esse comportamento pode mudar em uma versão futura.

---

## Requisição

`GET` `/api/v2/pam/sessions`

### Parâmetros de query

Todos os parâmetros de query são opcionais. Quando nenhum parâmetro é enviado, o endpoint retorna as sessões mais recentes usando a ordenação e o tamanho de página padrão.

Os nomes dos filtros são qualificados com o namespace ao qual pertencem, como `session.status` ou `device.id`. Nomes não qualificados retornam `400`.

#### Filtros

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `session.status` | string | Filtra pelo status da sessão. Valores aceitos: `pending`, `active`, `terminated`, `expired`. Valores separados por vírgula aplicam lógica OU. |
| `session.session_type` | string | Filtra pelo tipo de sessão. Valores aceitos: `web_proxy`, `terminal_proxy`, `rdp_proxy`, `database_proxy`, `segura_browser`, `tcp_tunneling`, `epm`. Valores separados por vírgula aplicam lógica OU. |
| `session.selection_mode` | string | Filtra pela forma como a credencial foi escolhida. Valores aceitos: `explicit`, `automatic`. |
| `session.protocol` | string | Filtra pela correspondência exata do protocolo, como `SSH`, `RDP` ou `HTTPS`. |
| `session.user` | string | Filtra pelo nome de usuário exato do usuário que solicitou a sessão. |
| `session.origin` | string | Filtra pelo endereço IP de origem exato. |
| `session.created_at_gte` | string | Retorna as sessões criadas a partir deste instante, no formato ISO 8601. Inclusivo. |
| `session.created_at_lte` | string | Retorna as sessões criadas até este instante, no formato ISO 8601. Inclusivo. |
| `device.id` | integer | Filtra pelo ID exato do dispositivo. |
| `credential.id` | integer | Filtra pelo ID exato da credencial. Corresponde à credencial efetiva, que é a credencial da macro de automação quando existe, e a credencial direta nos demais casos. |

Um valor de enum inválido retorna `422 api.enum.invalid_value`. Um `session.created_at_gte` posterior ao `session.created_at_lte` retorna `422 api.validation.invalid_date_range`.

Para as regras completas de validação de filtros e a lógica E/OU, consulte [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

#### Busca

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `search` | string | Busca por substring no identificador da sessão, no hostname do dispositivo e no nome de usuário da credencial. Mínimo de três caracteres. |

Diferente dos filtros, `search` não é qualificado com namespace. Enviar `session.search` retorna `400`, e um termo com menos de três caracteres retorna `400 api.request.bad_request`.

#### Ordenação

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `sort_by` | string | Um ou mais campos no formato `campo:asc` ou `campo:desc`, separados por vírgula e processados da esquerda para a direita. Padrão: `session.created_at:desc`. |

Os campos ordenáveis são `session.created_at`, `session.started_at` e `session.ended_at`. Um campo desconhecido retorna `422 api.sort.invalid_field`, e uma direção diferente de `asc` ou `desc` retorna `422 api.sort.invalid_direction`.

Os resultados incluem um critério de desempate interno único na mesma direção da ordenação. Isso mantém a paginação estável quando novas sessões são criadas enquanto você percorre as páginas.

#### Paginação

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `page` | integer | Número da página, a partir de `1`. Padrão: `1`. |
| `limit` | integer | Resultados por página. Mínimo `1`, máximo `200`. Padrão: `50`. |

Um `limit` maior que `200` retorna `422 api.pagination.limit.exceeded`.

Para sincronizar sessões de forma incremental, defina um piso com `session.created_at_gte` e siga `meta.links.next` até que o campo não esteja mais presente na resposta. Não percorra as páginas até `meta.pagination.total_pages`: os totais são informativos, e `meta.links.next` é a forma suportada de avançar.

Para as regras completas de paginação, consulte [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

#### Projeção de campos

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `fields` | string | Chaves canônicas a retornar, separadas por vírgula, como `session.status,device.hostname`. O campo `id` é sempre retornado. |

Uma chave desconhecida retorna `422 api.validation.invalid_field`. Para as regras completas de projeção, consulte [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

---

### Exemplo de requisição

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

---

## Resposta

```
HTTP/1.1 200 OK
```

Um filtro que não encontra correspondência retorna `200` com o array `data` vazio, e não um erro.

### Exemplo de corpo da resposta

```
{
    "data": [
        {
            "id": "789",
            "session": {
                "session_id": "S2026082912345",
                "session_type": "terminal_proxy",
                "protocol": "SSH",
                "status": "active",
                "user": "dalmeida",
                "justification": "Janela de manutenção 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"
        }
    }
}
```

### Campos do corpo da resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `data` | array de objetos | Sessões que correspondem à requisição. |
| `meta` | object | Metadados de paginação e links de navegação. |

#### `data`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| →`id` | string | Código de identificação único da sessão. Use este valor no path da requisição de [GET \| Listar uma sessão remota por [id]](/v4-2/docs/api-v2-get-list-a-remote-session). |
| →`session` | object | Atributos da sessão. |
| →`device` | object | Dispositivo ao qual a sessão se conectou. |
| →`credential` | object | Credencial utilizada pela sessão. `null` para sessões ad-hoc e do EPM que não utilizam uma credencial do cofre. |

#### `data.session`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| →→`session_id` | string | Identificador da sessão exibido aos usuários e referenciado em tickets de incidente. É o valor que o parâmetro `search` compara. |
| →→`session_type` | string | Tipo de sessão. Um entre `web_proxy`, `terminal_proxy`, `rdp_proxy`, `database_proxy`, `segura_browser`, `tcp_tunneling`, `epm`. |
| →→`protocol` | string | Protocolo utilizado pela sessão, como `SSH`, `RDP` ou `HTTPS`. |
| →→`status` | string | Status atual da sessão: `pending`, `active`, `terminated` ou `expired`. Derivado dos registros de data e hora da sessão, e não armazenado. |
| →→`user` | string | Nome de usuário do usuário que solicitou a sessão. |
| →→`justification` | string | Justificativa informada pelo usuário ao solicitar a sessão. |
| →→`access_period` | string | Janela de acesso aprovada como um intervalo ISO 8601 no formato `início/fim`. `null` quando a sessão não possui solicitação aprovada. |
| →→`origin` | string | Endereço IP de origem do usuário que solicitou a sessão. É um dado pessoal e é retornado integralmente para fins de auditoria. |
| →→`selection_mode` | string | Como a credencial foi escolhida: `explicit` quando o chamador ou a interface a selecionou, `automatic` quando o sistema a resolveu. |
| →→`created_at` | string | Data e hora em que a sessão foi solicitada, no formato ISO 8601 e em UTC. Exemplo: `2026-08-29T12:34:56+00:00`. |
| →→`started_at` | string | Data e hora em que a sessão iniciou, no formato ISO 8601 e em UTC. `null` enquanto a sessão está pendente e para reservas que expiraram sem iniciar. |
| →→`ended_at` | string | Data e hora em que a sessão terminou, no formato ISO 8601 e em UTC. Para sessões `expired`, é o instante em que a reserva expirou. `null` enquanto a sessão está ativa ou pendente. |
| →→`duration` | string | Tempo decorrido da sessão no formato `HH:MM:SS`. Avança enquanto a sessão está ativa, mantém o valor final após o encerramento e é `null` quando a sessão nunca iniciou. |

#### `data.device`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| →→`id` | integer | Código de identificação único do dispositivo. |
| →→`hostname` | string | Hostname do dispositivo. |

#### `data.credential`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| →→`id` | integer | Código de identificação único da credencial. |
| →→`username` | string | Nome de usuário da credencial utilizada pela sessão. O valor do segredo nunca é retornado. |

#### `meta`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| →`pagination` | object | Número da página, tamanho da página e totais de resultados. |
| →`links` | object | Links de navegação. `self` está sempre presente. `next` está presente até a última página, e sua ausência indica o fim do conjunto de resultados. |

              Atenção

              

A URL de acesso à sessão nunca é retornada por este endpoint. As URLs de sessão são de uso único e já estão expiradas para fins de leitura. A credencial é sempre retornada, porque saber qual credencial foi utilizada é um dado de auditoria.

---

## Erros

| Código HTTP | Código de erro | Causa possível | Solução |
| --- | --- | --- | --- |
| `400` | `api.request.bad_request` | Parâmetro de query desconhecido, nome de filtro não qualificado como `status` em vez de `session.status`, ou termo de `search` com menos de três caracteres. | Qualifique o nome do filtro com o seu namespace e verifique a grafia do parâmetro. |
| `401` | `api.auth.token.invalid` | Token bearer ausente, expirado ou inválido. | Solicite um novo token de acesso. |
| `422` | `api.enum.invalid_value` | Valor inválido para `session.status`, `session.session_type` ou `session.selection_mode`. | Envie um dos valores aceitos listados na tabela de filtros. |
| `422` | `api.validation.invalid_date_range` | `session.created_at_gte` é posterior a `session.created_at_lte`. | Corrija o intervalo de datas. |
| `422` | `api.pagination.limit.exceeded` | `limit` é maior que `200`. | Envie um `limit` de `200` ou menor. |
| `422` | `api.sort.invalid_field` | `sort_by` referencia um campo fora do conjunto ordenável. | Ordene por `session.created_at`, `session.started_at` ou `session.ended_at`. |
| `422` | `api.sort.invalid_direction` | `sort_by` utiliza uma direção diferente de `asc` ou `desc`. | Utilize `asc` ou `desc`. |
| `422` | `api.validation.invalid_field` | `fields` referencia uma chave canônica desconhecida. | Verifique os nomes das chaves nas tabelas de campos do corpo da resposta. |
| `422` | `api.request.invalid_param` | Um parâmetro possui o tipo incorreto, como um `device.id` não inteiro ou uma data não interpretável. | Corrija o tipo do parâmetro. |
| `429` | `rate_limit_exceeded` | O orçamento de requisições da janela atual foi esgotado. | Aguarde o número de segundos informado no header `Retry-After` e tente novamente. |
| `500` | `api.internal.error` | Erro interno do servidor. | Entre em contato com o suporte da Segura™. |

Para as mensagens de erro de autenticação e a política de `403` versus `404`, consulte [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

---

## Documentos relacionados

- [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [GET | Listar uma sessão remota por [id]](/v4-2/docs/api-v2-get-list-a-remote-session)
- [GET | Listar todas as sessões remotas](/v4-2/docs/api-get-list-all-remote-sessions)
- [Como gerenciar autorizações no A2A para a API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)