---
title: "List Embed Sessions"
method: GET
path: "/embed/sessions/{embedId}"
tags: ["Media Embed"]
---

# List Embed Sessions

`GET /embed/sessions/{embedId}`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/embed/sessions/{embedId}`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

List the viewing sessions on one embed, newest first by default. A session is one visit to the embed page by one browser: when it started and ended, how long the viewer was active, what they opened and watched, how many questions they asked, and where they came from.

Filter by date range, traffic type, identified or anonymous viewers, device, country, a single viewer or visitor, or a media file the session opened. Members without access to all folders only see embeds for media and folders they can open. Any other embed, or an embed that is deleted or in another workspace, returns 404.

## Path parameters

- `embedId` string, required

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `traffic` 'all' | 'people' | 'bots'
- `includeOwner` boolean
- `page` integer
- `pageSize` integer
- `search` string
- `viewer` 'all' | 'identified' | 'anonymous'
- `device` 'all' | 'desktop' | 'mobile' | 'tablet'
- `country` string
- `includeLegacy` boolean
- `viewerId` string
- `visitorId` string
- `mediaId` string
- `sort` 'startedAt:desc' | 'startedAt:asc' | 'activeMs:desc' | 'watchedMs:desc' | 'questions:desc'

## Response `200`

OK

- object
  - `status` 'success'
  - `data` object
    - `sessions` object[]: One page of sessions, sorted by `sort`. Bot visits also carry `bot` with `kind` (`render` or `crawler`) and an optional `name`.
      - `_id` string: The session's id. Use it with the session detail endpoint.
      - `sessionId` string: The id the browser gave the session.
      - `isLegacy` boolean: True for a visit recorded before session tracking. Its timing, media and question numbers are null.
      - `isOwner` boolean: True when the visit came from a member of your workspace.
      - `isLive` boolean: True when the viewer was active in the last minute and the session has not ended.
      - `visitorId` string: Anonymous id kept in the viewer's browser. Absent on some legacy visits.
      - `viewerId` string: Present when the viewer entered their email on the embed.
      - `email` string: The email the viewer entered, when they did.
      - `name` string: The name the viewer entered, when they did.
      - `startedAt` string, date-time
      - `lastActiveAt` string, date-time: Last time the viewer interacted. Absent when unknown.
      - `endedAt` string, date-time: When the session ended. Absent while it is still open. A session with no activity for 30 minutes counts as ended at its last activity.
      - `durationMs` integer, nullable: Wall clock time from start to last activity, in milliseconds. Null on legacy visits.
      - `activeMs` integer, nullable: Time the viewer was active on the page, in milliseconds. Null on legacy visits.
      - `mediaOpened` integer, nullable: Media files opened. Null on legacy visits.
      - `watchedMs` integer, nullable: Media playback time, in milliseconds. Null on legacy visits.
      - `questions` integer, nullable: Questions asked to the AI chat. Null on legacy visits.
      - `client` object: Where the visit came from and on what device, when known. Every field is optional.
        - `country` string: Country name.
        - `region` string
        - `city` string
        - `continent` string
        - `timeZone` string
        - `browser` string
        - `os` string
        - `referer` string
        - `referrerHost` string: Host of the referring page.
        - `screen` string
        - `language` string
        - `embedded` boolean: True when the embed was loaded inside another site's page.
        - `deviceType` string: The device type the browser reports, such as `mobile` or `tablet`. Usually absent on desktop browsers.
      - `campaign` object: UTM tags on the visit, when present. Every field is optional.
        - `utmSource` string
        - `utmMedium` string
        - `utmCampaign` string
      - `bot` object: Present when the visit was a detected bot or crawler.
        - `kind` 'render' | 'crawler'
        - `name` string
    - `totalCount` integer: Sessions matching the filters, across all pages.
    - `page` integer: The page returned, starting at 0.
    - `pageSize` integer: The page size used.

## Other responses

- `400`: A query parameter failed validation
- `404`: Embed not found

## Changes

- **2026-10-19** `52d777e6d46e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/speakai/apis/speak-ai-api/changes/embed/sessions/:embedId/get.md)

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)