Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zitadel/zitadel/llms.txt

Use this file to discover all available pages before exploring further.

Searches for sessions matching the given query. You can search by session ID, user ID, creation date, creator, user agent, or expiration date.

​
HTTP Request

POST /v2/sessions/search

​
Permissions

Requires session.read permission, or no permission if searching for your own sessions.

​
Request Body

​
query
object
List limitations and ordering.
​
offset
integer
Number of results to skip.
​
limit
integer
Maximum number of results to return.
​
asc
boolean
Sort order: true for ascending, false for descending.
​
queries
array
Array of search criteria. Multiple queries are combined with AND logic.
​
ids_query
object
Search for sessions with specific IDs.
​
ids
array
List of session IDs to search for.
​
user_id_query
object
Search for sessions of a specific user.
​
id
string
ID of the user whose sessions to find.
​
creation_date_query
object
Search based on session creation date.
​
creation_date
timestamp
The date to compare against.
​
method
enum
Comparison method: EQUALS, GREATER_THAN, LESS_THAN.
​
creator_query
object
Search for sessions created by a specific user.
​
id
string
ID of the creator. If empty, uses the calling user’s ID.
​
user_agent_query
object
Search based on user agent information.
​
fingerprint_id
string
Fingerprint ID of the user agent. Set empty to use the user agent from the current call.
​
expiration_date_query
object
Search based on session expiration date.
​
expiration_date
timestamp
The date to compare against.
​
method
enum
Comparison method: EQUALS, GREATER_THAN, LESS_THAN.
​
sorting_column
enum
The column to sort by. Options:
  • SESSION_FIELD_NAME_CREATION_DATE (default)

​
Response

​
details
object
Information about the search results.
​
total_result
integer
Total number of sessions matching the query.
​
processed_sequence
string
The sequence number processed.
​
view_timestamp
timestamp
Timestamp of the view.
​
sessions
array
Array of sessions matching the query.
​
id
string
Unique identifier of the session.
​
creation_date
timestamp
When the session was created.
​
change_date
timestamp
When the session was last updated.
​
sequence
string
The sequence number of the session.
​
factors
object
Verification factors that have been checked.
​
user
object
User verification factor.
​
verified_at
timestamp
When the user was verified.
​
id
string
User ID.
​
login_name
string
User’s login name.
​
display_name
string
User’s display name.
​
organization_id
string
ID of the organization the user belongs to.
​
password
object
Password verification factor.
​
verified_at
timestamp
When the password was verified.
​
web_auth_n
object
WebAuthN verification factor.
​
verified_at
timestamp
When WebAuthN was verified.
​
user_verified
boolean
Whether user presence was verified.
​
metadata
object
Custom metadata stored on the session.
​
user_agent
object
Information about the user agent that created the session.
​
expiration_date
timestamp
When the session will automatically expire (if set).

​
Example Request

curl -X POST 'https://api.zitadel.cloud/v2/sessions/search' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "limit": 10,
      "asc": false
    },
    "queries": [
      {
        "user_id_query": {
          "id": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a"
        }
      }
    ],
    "sorting_column": "SESSION_FIELD_NAME_CREATION_DATE"
  }'

​
Example Response

{
  "details": {
    "total_result": "3",
    "processed_sequence": "12345",
    "view_timestamp": "2024-03-15T10:30:00.000Z"
  },
  "sessions": [
    {
      "id": "222430354126975533",
      "creation_date": "2024-03-15T09:00:00.000Z",
      "change_date": "2024-03-15T09:15:00.000Z",
      "sequence": "5",
      "factors": {
        "user": {
          "verified_at": "2024-03-15T09:00:00.000Z",
          "id": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
          "login_name": "user@example.com",
          "display_name": "John Doe",
          "organization_id": "69629023906488334"
        },
        "password": {
          "verified_at": "2024-03-15T09:00:00.000Z"
        },
        "totp": {
          "verified_at": "2024-03-15T09:15:00.000Z"
        }
      },
      "metadata": {},
      "user_agent": {
        "ip": "192.168.1.100",
        "description": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
      },
      "expiration_date": "2024-03-15T17:00:00.000Z"
    }
  ]
}

​
Notes

  • Multiple queries are combined with AND logic
  • Results are paginated - use offset and limit for pagination
  • The details.total_result field shows the total number of matching sessions
  • Sessions can be filtered by multiple criteria simultaneously