> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keylogroup.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Sessions

> Retrieve a list of sessions for a workspace. Optionally return the session closest to a provided timestamp.

# Retrieve Sessions

Use this endpoint to retrieve the sessions stored for a specific workspace.

This is the primary **read** endpoint for sessions and is typically used to:

* populate dashboards
* load recent session history
* locate the session closest to a given timestamp (using `start_time`)

***

## Endpoint

**GET** `/sessions/list/{workspaceId}`

***

## Authentication

This endpoint requires a valid workspace API key.

Include the API key in the request header:

* **Header:** `x-api-key`
* **Value:** `<your-api-key>`

If the API key is missing or invalid, the API will return **401 Unauthorized**.

***

## Path Parameters

### `workspaceId` (required)

The workspace identifier that owns the sessions table.

* **Type:** `string`
* **Example:** `b0a6c81e-2d5d-4f29-bb4b-9a1e0d9f6c11`

***

## Query Parameters

### `start_time` (optional)

If provided, the API returns the session whose `start_time` is **closest** to the timestamp you send.

* **Type:** `string`
* **Format:** `date-time` (ISO 8601)
* **Example:** `2026-02-14T18:30:00Z`

***

## Behavior

This endpoint supports two retrieval modes.

### 1) Default mode (full session history)

When `start_time` is not provided:

* the API returns **all sessions** for the workspace
* results are ordered by `start_time DESC` (most recent first)

### 2) Closest-session lookup

When `start_time` is provided:

* the API calculates the absolute time difference between each stored session and the requested timestamp
* the API returns the **single closest session**
* results are ordered by smallest time difference

> Note: This is not a range filter. Only the closest matching session is returned.

***

## Example Requests

Retrieve all sessions

<CodeBlock language="bash">
  {`curl -X GET "https://api.keyloroblox.xyz/sessions/list/YOUR_WORKSPACE_ID" \\
    -H "x-api-key: YOUR_API_KEY"`}
</CodeBlock>

Retrieve the closest session to a timestamp

<CodeBlock language="bash">
  {`curl -X GET "https://api.keyloroblox.xyz/sessions/list/YOUR_WORKSPACE_ID?start_time=2026-02-14T18:30:00Z" \\
    -H "x-api-key: YOUR_API_KEY"`}
</CodeBlock>

***

## Responses

### 200 OK

Returns an array of session records.

> The response structure depends on your workspace session table (`ws_sessions_{workspaceId}`).

Example response (multiple sessions)

<CodeBlock language="json">
  {`[
    {
      "id": "b6cbbd2a-7f7a-4f67-bef1-1a3f6a4d4f19",
      "workspace_id": "b0a6c81e-2d5d-4f29-bb4b-9a1e0d9f6c11",
      "title": "Training Session",
      "type": "training",
      "host_id": "48192015",
      "co_host_id": null,
      "start_time": "2026-02-14T18:00:00.000Z",
      "duration_minutes": 60,
      "groups": ["Alpha", "Bravo"],
      "created_at": "2026-02-14T17:59:12.000Z"
    },
    {
      "id": "3f6d9e31-3f8f-4e9a-9c1a-20cc1d7c31dd",
      "workspace_id": "b0a6c81e-2d5d-4f29-bb4b-9a1e0d9f6c11",
      "title": "Interview",
      "type": "interview",
      "host_id": "48192015",
      "co_host_id": "12044991",
      "start_time": "2026-02-13T20:30:00.000Z",
      "duration_minutes": 30,
      "groups": [],
      "created_at": "2026-02-13T20:25:00.000Z"
    }
    ]`}
</CodeBlock>

***

### 401 Unauthorized

Returned when the API key is missing or invalid.

Example response (missing key)

<CodeBlock language="json">
  {`{
    "error": "API key missing"
    }`}
</CodeBlock>

Example response (invalid key)

<CodeBlock language="json">
  {`{
    "error": "Unauthorized: invalid API key"
    }`}
</CodeBlock>

***

### 500 Internal Server Error

Returned when the database query fails.

<CodeBlock language="json">
  {`{
    "error": "Failed to fetch sessions"
    }`}
</CodeBlock>

***

## Internal Data Source (Implementation Detail)

Sessions are read from a workspace-scoped table:

<CodeBlock language="txt">
  {`ws_sessions_{workspaceId}`}
</CodeBlock>

This design ensures session data is isolated per workspace and prevents cross-workspace access.


## OpenAPI

````yaml GET /sessions/list/{workspaceId}
openapi: 3.0.0
info:
  title: Keylo API
  version: 1.0.0
  description: Keylo public API documentation
servers:
  - url: https://api.keyloroblox.xyz
security: []
tags: []
paths:
  /sessions/list/{workspaceId}:
    get:
      summary: Get sessions list
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
        - name: start_time
          in: query
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Returns list of sessions
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````