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

# Read Sessions

`GET /api/v1/sessions`

## Request

- Base URL: `https://api.gnosari.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gnosari.com/api/v1/sessions`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-AUTH-TOKEN`

Retrieve sessions for current user's account.

By default, only USER sessions are returned. Use include_internal=true to see all sessions.

Supports filtering by:
- session_type: Filter by specific session type (USER, INTERNAL, DEBUG)
- include_internal: Include all session types (overrides session_type filter)
- team_id: Filter by team ID
- agent_id: Filter by agent ID
- team_identifier: Filter by team identifier string (e.g., "sales-team")
- agent_identifier: Filter by agent identifier string (e.g., "support-agent")
- search: Search keyword in session message content
- from_date: Sessions created on or after this date (ISO format: 2024-01-01T00:00:00Z)
- to_date: Sessions created on or before this date (ISO format)

Supports sorting by any session field and pagination.

## Query parameters

- `sort_by` string: Field to sort by
- `sort_order` string: Sort order: ascending or descending
- `team_id` integer, nullable: Filter by team ID
- `agent_id` integer, nullable: Filter by agent ID
- `team_identifier` string, nullable: Filter by team identifier string
- `agent_identifier` string, nullable: Filter by agent identifier string
- `search` string, nullable: Search keyword in session messages
- `from_date` string, nullable: Filter sessions created on or after this date (ISO format)
- `to_date` string, nullable: Filter sessions created on or before this date (ISO format)
- `session_type` 'USER' | 'INTERNAL' | 'DEBUG': Session type for visibility control. Following SOLID principles: - Single Responsibility: Each type has one clear visibility pattern - Open/Closed: New types can be added without modifying existing code
- `include_internal` boolean: Include INTERNAL and DEBUG sessions (admin/debug mode)
- `skip` integer: Number of items to skip
- `limit` integer: Maximum items to return

## Response `200`

Successful Response

- PaginatedResponseSessionWithMessageCount
  - `data` SessionWithMessageCount[], required
    - `session_id` string, required
    - `team_id` integer, nullable
    - `agent_id` integer, nullable
    - `team_identifier` string, nullable
    - `agent_identifier` string, nullable
    - `summary` string, nullable
    - `summary_metadata` object, nullable: Metadata from summary generation: key_topics, sentiment, action_items, primary_intent
    - `session_type` 'USER' | 'INTERNAL' | 'DEBUG': Session type for visibility control. Following SOLID principles: - Single Responsibility: Each type has one clear visibility pattern - Open/Closed: New types can be added without modifying existing code
    - `channel` 'JOINA_CHAT' | 'QR' | 'WIDGET' | 'INTERNAL' | 'API': Origin channel a session was created on — informational display metadata. Set once at creation on the client-known surface (``POST /sessions``) and surfaced on reads so the Collected Data inbox can render "via joina.chat" per record. Mirrors ``SessionType``'s varchar+StrEnum shape MINUS the index. INFORMATIONAL AND FORGEABLE BY DESIGN: it rides a public unauthenticated ``POST /sessions`` and is enum-validated (invalid → 422) but NEVER drives authorization or visibility — that stays ``session_type``. Do not "fix" this as a security hole.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `message_count` integer, required
    - `first_message` SessionMessage
      - `message_data` string, required
      - `id` integer, required
      - `session_id` string, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `attachments` MessageAttachmentRef[]: Attachment references parsed from message_data content parts (Phase 7). Empty for text-only messages.
        - `asset_id` string, required
        - `kind` string, required: asset.kind vocabulary: image | document
        - `filename` string, nullable
    - `messages_overview` SessionMessage[]
      - `message_data` string, required
      - `id` integer, required
      - `session_id` string, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `attachments` MessageAttachmentRef[]: Attachment references parsed from message_data content parts (Phase 7). Empty for text-only messages.
        - `asset_id` string, required
        - `kind` string, required: asset.kind vocabulary: image | document
        - `filename` string, nullable
    - `team` TeamInfo
      - `id` integer, required
      - `name` string, required
      - `identifier` string, nullable
      - `agents` AgentInfo[]
        - `id` integer, required
        - `name` string, required
        - `identifier` string, nullable
    - `agent` AgentInfo
      - `id` integer, required
      - `name` string, required
      - `identifier` string, nullable
  - `pagination` PaginationMeta, required
    - `total` integer, required
    - `skip` integer, required
    - `limit` integer, required
    - `has_more` boolean, required

## Other responses

- `422`: Validation Error

---

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