---
title: "List portal sessions"
method: POST
path: "/v2/portal.listSessions"
tags: ["portal"]
---

# List portal sessions

`POST /v2/portal.listSessions`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/portal.listSessions`
- Auth: HTTP bearer

List the end users holding a revocable session on a portal, with each
end user's sessions.

Unreleased and subject to change without notice.

A session is revocable until it expires or is revoked. That includes
sessions whose portal URL was created but not opened yet. Pass an end
user's `externalId` to `portal.revokeSession` to end their sessions.

**Required Permissions**

Your root key must have one of:
- `portal.*.create_portal_session` (for any portal in the workspace)
- `portal.<portal_id>.create_portal_session` (for a specific portal)

It also accepts `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/sessions/*`
with `#read` or `#write`. Reading the portal itself is not enough.

Without the permission this returns **404**, not 403.

## Request body

- V2PortalListSessionsRequestBody
  - `portal` string, required: Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `limit` integer: Maximum number of end users to return per request.
  - `cursor` string: Pagination cursor from a previous response to fetch the next page. Use when `hasMore: true` in the previous response.
  - `search` string: Returns only end users whose `externalId` starts with this string. Matching is case-sensitive, and `%` and `_` match literally.

## Response `200`

One page of end users with revocable sessions.

- V2PortalListSessionsResponseBody
  - `meta` Meta, required: Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2PortalListSessionsResponseData[], required: End users with revocable sessions, ordered by `externalId`.
    - `externalId` string, required: The end user's identifier, as passed to `portal.createSession`.
    - `sessions` V2PortalListSessionsSession[], required: The end user's revocable sessions, newest first.
      - `id` string, required: The session id.
      - `status` 'pending' | 'active', required: `pending` when the portal URL was created but not opened yet. `active` when the end user opened it.
      - `createdAt` integer, required: When the session was created, in Unix milliseconds.
      - `expiresAt` integer, required: When the session stops working, in Unix milliseconds. For a `pending` session this is when its portal URL expires.
      - `scopes` string[], required: The capabilities the session was created with.
  - `pagination` Pagination, required: Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
    - `cursor` string: Opaque pagination token for retrieving the next page of results. Include this exact value in the cursor field of subsequent requests. Cursors are temporary and may expire after extended periods.
    - `hasMore` boolean, required: Indicates whether additional results exist beyond this page. When true, use the cursor to fetch the next page. When false, you have reached the end of the result set.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `404`: No such portal, or your root key may not see its sessions.
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-10-02** `4eaa6e874263`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/portal.listSessions/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)