Filtering Sessions

The Sessions API provides powerful filtering capabilities to help you find specific sessions based on user IDs, time ranges, session status, and more. This guide covers all available filter parameters and common filtering patterns.

Available Filter Parameters

The GET /v2/sessions endpoint accepts the following query parameters:

Parameter	Type	Required	Description
`experienceId`	UUID	Yes	The experience ID to filter sessions for
`userId`	string	No	Filter by user ID (email, UUID, or custom identifier, case-insensitive)
`startDate`	ISO 8601 datetime	No	Filter sessions created on or after this date
`endDate`	ISO 8601 datetime	No	Filter sessions created on or before this date
`status`	enum	No	Filter by session status: `active`, `completed`, or `expired`
`sortBy`	enum	No	Sort by `created_at` or `updated_at` (default: `created_at`)
`sortOrder`	enum	No	Sort order: `asc` or `desc` (default: `desc`)
`offset`	integer	No	Pagination offset (default: 0)
`limit`	integer	No	Results per page (default: 50, max: 100)

User ID Format

The userId parameter is flexible and supports multiple formats:

UUID: Standard UUID v4 identifiers (e.g., 550e8400-e29b-41d4-a716-446655440000)
Email: User email addresses (e.g., user@example.com)
Custom strings: Any string up to 255 characters (e.g., customer-12345, acct_abc123)

User IDs are normalized to lowercase and matched exactly. The parameter cannot contain whitespace or control characters.

Basic Filtering

List All Sessions for an Experience

// List all session IDs for an experience
const params = new URLSearchParams({
  experienceId: "your-experience-id",
  limit: "50", // Default: 50, max: 100
  offset: "0", // Default: 0
});

const response = await fetch(`https://nexus-api.uat.knowbl.com/api/v2/sessions?${params}`, {
  headers: {
    Authorization: `Bearer ${ACCESS_TOKEN}`,
  },
});

const data = await response.json();
console.log(`Found ${data.pagination.total} sessions`);
console.log(`Session IDs:`, data.sessionIds);

This returns an array of session IDs and pagination metadata. Note that only session IDs are returned for performance - full session details must be fetched separately.

Filter by User ID

Filter sessions for a specific user. This is particularly useful for:

Viewing a user’s conversation history
Analyzing user engagement patterns
Building user-specific dashboards

// Filter sessions by user ID (supports email, UUID, or custom identifier)
const params = new URLSearchParams({
  experienceId: "your-experience-id",
  userId: "user@example.com", // or UUID, or "customer-12345"
});

const response = await fetch(`https://nexus-api.uat.knowbl.com/api/v2/sessions?${params}`, {
  headers: {
    Authorization: `Bearer ${ACCESS_TOKEN}`,
  },
});

const data = await response.json();
console.log(`Found ${data.pagination.total} sessions for user`);
console.log(`Session IDs:`, data.sessionIds);

Filter by Session Status

Filter sessions by their lifecycle state:

active: Sessions currently open for new turns
completed: Sessions explicitly marked as finished
expired: Sessions marked as expired based on business rules

// Filter sessions by status
const params = new URLSearchParams({
  experienceId: "your-experience-id",
  status: "active", // Options: "active", "completed", "expired"
});

const response = await fetch(`https://nexus-api.uat.knowbl.com/api/v2/sessions?${params}`, {
  headers: {
    Authorization: `Bearer ${ACCESS_TOKEN}`,
  },
});

const data = await response.json();
console.log(`Found ${data.pagination.total} active sessions`);
console.log(`Session IDs:`, data.sessionIds);

Filter by Date Range

Find sessions created within a specific time period:

// Filter sessions by date range
const startDate = new Date("2025-10-01T00:00:00.000Z").toISOString();
const endDate = new Date("2025-10-31T23:59:59.999Z").toISOString();

const params = new URLSearchParams({
  experienceId: "your-experience-id",
  startDate,
  endDate,
  sortBy: "created_at", // Options: "created_at", "updated_at"
  sortOrder: "desc", // Options: "asc", "desc"
});

const response = await fetch(`https://nexus-api.uat.knowbl.com/api/v2/sessions?${params}`, {
  headers: {
    Authorization: `Bearer ${ACCESS_TOKEN}`,
  },
});

const data = await response.json();
console.log(`Found ${data.pagination.total} sessions in date range`);
console.log(`Session IDs:`, data.sessionIds);

Date Range Best Practices

Use ISO 8601 format for dates: YYYY-MM-DDTHH:mm:ss.sssZ
Times are interpreted as UTC
Both startDate and endDate are inclusive
Omit startDate to get all sessions up to endDate
Omit endDate to get all sessions from startDate onwards

Combined Filtering

Combine multiple filters to narrow down results:

// Combine multiple filters: user + status + date range
const sevenDaysAgo = new Date();
sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);

const params = new URLSearchParams({
  experienceId: "your-experience-id",
  userId: "user@example.com",
  status: "active",
  startDate: sevenDaysAgo.toISOString(),
  sortBy: "updated_at",
  sortOrder: "desc",
});

const response = await fetch(`https://nexus-api.uat.knowbl.com/api/v2/sessions?${params}`, {
  headers: {
    Authorization: `Bearer ${ACCESS_TOKEN}`,
  },
});

const data = await response.json();
console.log(
  `Found ${data.pagination.total} active sessions for user in last 7 days`,
);
console.log(`Session IDs:`, data.sessionIds);

This example finds all active sessions for a specific user created in the last 7 days, useful for:

Identifying ongoing conversations
Monitoring recent user activity
Tracking active support sessions

Pagination

Handle large result sets with pagination:

// Paginate through all sessions
const pageSize = 50;
let offset = 0;
let hasMore = true;

while (hasMore) {
  const params = new URLSearchParams({
    experienceId: "your-experience-id",
    limit: pageSize.toString(),
    offset: offset.toString(),
  });

  const response = await fetch(`https://nexus-api.uat.knowbl.com/api/v2/sessions?${params}`, {
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
    },
  });

  const data = await response.json();
  console.log(
    `Page ${offset / pageSize + 1}: ${data.sessionIds.length} sessions`,
  );

  // Process sessions...
  for (const sessionId of data.sessionIds) {
    console.log(`Processing session: ${sessionId}`);
  }

  // Check if there are more pages
  offset += pageSize;
  hasMore = offset < data.pagination.total;
}

console.log("Finished processing all sessions");

Pagination Best Practices

Default limit is 50 sessions per page (max: 100)
Use the total field to calculate total pages
Maintain consistent sortBy and sortOrder across pages
Consider caching results for frequently accessed pages

Fetching Full Session Details

The list endpoint returns only session IDs for efficiency. To get full conversation history:

// Step 1: Filter sessions to get IDs
const filterParams = new URLSearchParams({
  experienceId: "your-experience-id",
  userId: "user@example.com",
  status: "completed",
  limit: "10",
});

const listResponse = await fetch(`https://nexus-api.uat.knowbl.com/api/v2/sessions?${filterParams}`, {
  headers: {
    Authorization: `Bearer ${ACCESS_TOKEN}`,
  },
});

const { sessionIds } = await listResponse.json();
console.log(`Found ${sessionIds.length} completed sessions for user`);

// Step 2: Fetch full details for each session
const sessions = [];
for (const sessionId of sessionIds) {
  const detailParams = new URLSearchParams({
    experienceId: "your-experience-id",
  });

  const detailResponse = await fetch(
    `https://nexus-api.uat.knowbl.com/api/v2/sessions/${sessionId}?${detailParams}`,
    {
      headers: {
        Authorization: `Bearer ${ACCESS_TOKEN}`,
      },
    },
  );

  const session = await detailResponse.json();
  sessions.push(session);

  console.log(`Session ${sessionId}:`);
  console.log(`  Status: ${session.status}`);
  console.log(`  Turns: ${session.turns.length}`);
  console.log(`  Created: ${session.createdAt}`);
}

// Now you have full session details with conversation history
console.log(`Loaded ${sessions.length} complete sessions`);

This two-step approach:

Filter efficiently: Get session IDs matching your criteria
Fetch details on-demand: Retrieve full conversation history only for sessions you need

Performance Considerations

List endpoint is optimized with database indexes on experience_id, user_id, and status
Fetching full details includes all conversation turns, which can be large for long sessions
Consider implementing client-side caching for frequently accessed sessions
Use pagination to avoid loading too many sessions at once

Common Use Cases

User Conversation History

Retrieve all sessions for a specific user, sorted by most recent:

const params = new URLSearchParams({
  experienceId: "your-experience-id",
  userId: "user@example.com",
  sortBy: "created_at",
  sortOrder: "desc",
  limit: "20",
});

Active Sessions Dashboard

Monitor all currently active sessions:

const params = new URLSearchParams({
  experienceId: "your-experience-id",
  status: "active",
  sortBy: "updated_at",
  sortOrder: "desc",
});

Analytics Time Range

Get completed sessions from last month for analytics:

const startDate = new Date("2025-10-01T00:00:00.000Z").toISOString();
const endDate = new Date("2025-10-31T23:59:59.999Z").toISOString();

const params = new URLSearchParams({
  experienceId: "your-experience-id",
  status: "completed",
  startDate,
  endDate,
});

Error Handling

Common error scenarios:

Invalid Experience ID

{
  "statusCode": 404,
  "message": "Experience {experienceId} not found"
}

Invalid Date Format

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "startDate must be a valid ISO 8601 datetime string"
  ]
}

Invalid User ID Format

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "User ID cannot contain whitespace or control characters"
  ]
}

Next Steps

Session Lifecycle - Understanding session states and transitions
Session Metadata - Using metadata with filtered sessions
Query API - Creating sessions through query interactions