List and sort sessions

List session metadata by owner or namespace, sort results, and follow pagination.

Use session listing to let a user reopen an earlier conversation. The session rows contain IDs and available owner, timestamp, and namespace metadata. They do not contain conversation events or summary text. Retrieve the selected session with memory.conversation(owner=..., session_id=...).transcript() (Python), iris agent-memory sessions show, or GET /iris/data/v1/agent-memory/stores/{storeId}/sessions/{sessionId} to build the agent's conversation context.

Choose a listing operation

The REST operation returns items and an optional nextCursor. It does not return a total count. memory.sessions(owner) follows every page for you and returns only the IDs.

These examples continue from the quickstart. Load the same .env connection values and reuse its user ID. Expand an example to copy a complete program that connects for you.

Each run repeats every write in the program. Session-event writes and memory creates with a new idempotency key add new records, so run cleanup or change the identifiers before rerunning.

To list the quickstart user's session IDs:

for session_id in memory.sessions(OWNER_ID):
    print(session_id)

curl --fail-with-body --silent --show-error --get \
  "$MEMORY_API/sessions" -H "$AUTH" \
  --data-urlencode "ownerId=$OWNER_ID" | jq -r '.items[].sessionId'

set -euo pipefail

iris agent-memory sessions list --owner quickstart-user

For a user's personal conversations, set ownerId to the user's authenticated ID. The session owner is the first event's actorId. Add namespaceId to require an exact namespace ID as well. It does not include descendants, deprecated namespace labels, or sessions without a namespace resource. Owner and namespace matching is case-sensitive.

A request without filters must set includeAll=true. Do not combine includeAll=true with either filter. Authorize store-wide or shared namespace listing in your application before making the request. A filter selects records; it does not establish the caller's right to access them.

Sort and paginate session rows

The default is sortBy=updatedAt and sortOrder=DESC, so recent activity appears first. sortBy accepts sessionId, createdAt, or updatedAt. sortOrder accepts ASC or DESC. When omitted, it is ascending for sessionId and descending for timestamps. limit accepts 1–200 and defaults to 100.

To list session rows for one owner, with the most recently updated sessions first, follow every page:

cursor = None
while True:
    page = memory.client.list_sessions(
        owner_id=OWNER_ID,
        sort_by=models.SessionListSortBy.UPDATED_AT,
        sort_order=models.SessionListSortOrder.DESC,
        limit=20,
        cursor=cursor,
    )
    for session in page.items:
        print(session.session_id, session.updated_at, session.namespace_id)
    cursor = page.next_cursor
    if not cursor:
        break

CURSOR=''
while :; do
  PAGE=$(curl --fail-with-body --silent --show-error --get \
    "$MEMORY_API/sessions" -H "$AUTH" \
    --data-urlencode "ownerId=$OWNER_ID" \
    --data-urlencode 'sortBy=updatedAt' --data-urlencode 'sortOrder=DESC' \
    --data-urlencode 'limit=20' ${CURSOR:+--data-urlencode "cursor=$CURSOR"})
  jq -c '.items[] | {sessionId, updatedAt, namespaceId}' <<< "$PAGE"
  CURSOR=$(jq -r '.nextCursor // empty' <<< "$PAGE")
  [ -n "$CURSOR" ] || break
done

Pass each returned nextCursor as cursor. Keep filters and sort options unchanged; the cursor is bound to them. Stop when the cursor is absent. The cursor is opaque, so URL-encode it in REST requests. Changing a filter or sort requires a new request without the old cursor.

Sessions stored without owner or timestamp metadata can omit ownerId, createdAt, or updatedAt. Handle those missing values when rendering a conversation list. A row's timestamps describe session metadata; they do not promise that background extraction or summarization has completed.