GET/sessions

List all sessions

Returns a list of sessions matching the provided criteria. The sessions are returned sorted by creation date, with the newest sessions appearing first.

Note: This endpoint does not return all sessions that have ever existed. Old and inactive sessions are periodically cleaned up and will not be included in the results.

Deprecation Notice (2024-01-01): All parameters were initially considered optional, however moving forward at least one of client_id or user_id parameters should be provided.

6 parameters

client_idstringoptional

List sessions for the given client

user_idstringoptional

List sessions for the given user

statusstringoptional

Filter sessions by the provided status

Allowed:abandonedactiveendedexpiredremovedreplacedrevoked

paginatedbooleanoptional

Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.

limitintegeroptional

Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.

Default:10

offsetintegeroptional

Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.

Default:0

4 status codes

200Success

objectstringrequired

String representing the object's type. Objects of the same type share the same value.

Allowed:session

idstringrequired

user_idstringrequired

client_idstringrequired

actorobjectoptional

statusstringrequired

Allowed:activerevokedendedexpiredremovedabandonedreplacedpending

last_active_organization_idstringoptional

last_active_atintegerrequired

latest_activityobjectoptional

expire_atintegerrequired

Unix timestamp of expiration.

abandon_atintegerrequired

Unix timestamp of abandonment.

updated_atintegerrequired

Unix timestamp of last update.

created_atintegerrequired

Unix timestamp of creation.

tasksarray<object>optional

400Request was not successful

errorsarray<object>required

metaobjectoptional

clerk_trace_idstringoptional

401Authentication invalid

errorsarray<object>required

metaobjectoptional

clerk_trace_idstringoptional

422Invalid request parameters

errorsarray<object>required

metaobjectoptional

clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 422 is returned: Invalid request parameters.

import { Client } from "@octridev/clerk";

const client = new Client({
  baseUrl: "https://api.clerk.com/v1",
  auth: { bearer: process.env.API_TOKEN },
});

const result = await client.sessions.list({
  clientId: "c0a80123-4567-89ab-cdef-0123456789ab",
  userId: "c0a80123-4567-89ab-cdef-0123456789ab",
  status: "example",
  paginated: "example",
  limit: 20,
});

[
  {
    "object": "session",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active",
    "last_active_organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "last_active_at": 1,
    "latest_activity": {
      "object": "example_value",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "device_type": "example_value",
      "is_mobile": true,
      "browser_name": "Example Name",
      "browser_version": "example_value",
      "ip_address": "example_value",
      "city": "example_value",
      "country": "GB"
    },
    "expire_at": 1,
    "abandon_at": 1,
    "updated_at": "2026-01-15T09:00:00Z",
    "created_at": 1,
    "tasks": [
      {
        "key": "example_key_abc123"
      }
    ]
  }
]

Request

Response

Errors