---
title: "List sessions"
method: GET
path: "/api/v1/sessions"
tags: ["Sessions"]
---

# List sessions

`GET /api/v1/sessions`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/sessions`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Lists the sessions you own (called "notebooks" in the product UI), newest first. Sessions shared with you are not included; read one of those by id with `GET /api/sessions/{id}`. Each item has the same shape `GET /api/sessions/{id}` returns. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`. Changing `search`, `surface` or `origin` starts a new listing, so drop the cursor when you do. An API key needs `notebooks:read` or `notebooks:write`.

## Query parameters

- `limit` integer
- `cursor` string
- `search` string: Case-insensitive substring match on the session name, its summary, or a tag name.
- `surface` string: Lists only sessions of this product surface. When omitted, only sessions with no surface are listed.
- `origin` 'web' | 'api' | 'slack' | 'cli' | 'agent': Lists only sessions created through this channel. `web` also matches sessions with no recorded origin.

## Response `200`

One page of sessions, newest first by `id`.

- ListSessionsResponse200
  - `data` object[], required
    - `id` string, required
    - `_id` string
    - `name` string, required
    - `userId` string, required
    - `knowledgeIds` string[]
    - `artifactIds` string[]
    - `tags` object[]
      - `name` string, required
      - `strength` number, required
    - `forceKnowledgeRetrieval` boolean
    - `retrievalTags` string[]
    - `lakeScopeExplicit` boolean: True when `retrievalTags` is a deliberate choice, so an empty list means "no lake" rather than "any".
    - `includeLibraryFiles` boolean: Whether the session grounds on your own library alongside its lakes. Absent when never set.
    - `lastUsedModel` string, nullable
    - `firstCreated` string, date-time, required
    - `lastUpdated` string, date-time, required
  - `next_cursor` string, nullable, required

## Other responses

- `401`: Missing or invalid credentials.
- `403`: The API key holds neither `notebooks:read` nor `notebooks:write`.
- `405`: The path does not serve this HTTP method.
- `422`: `limit` is out of range, a filter is malformed, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.
- `429`: Per-user rate limit exceeded.

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/0de0bdb0d113?raw)