Media Embed

List Embed Sessions

Changed on

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.

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

Path parameters

embedIdstring required

The _id of the embed, as returned when you create or check an embed. Must be a 24 character hex id.

Query parameters

fromstring date-time

Only sessions started at or after this time, as an ISO 8601 date. Optional. Leave it out for no lower bound.

tostring date-time

Only sessions started at or before this time, as an ISO 8601 date. Optional. Leave it out for no upper bound.

traffic'all' | 'people' | 'bots'

Which visits to count: everyone, only people, or only detected bots and crawlers. Optional. Defaults to all.

includeOwnerboolean

Count visits by members of your own workspace. Optional. Defaults to false.

pageinteger

Page to return, starting at 0. Optional. Defaults to 0.

pageSizeinteger

Sessions per page, from 1 to 100. Optional. Defaults to 25.

searchstring

Match sessions whose viewer email contains this text, or whose visitor id starts with it. Not case sensitive. Optional. At most 100 characters. An empty string is ignored.

viewer'all' | 'identified' | 'anonymous'

Only sessions where the viewer entered an email (identified), only those where they did not (anonymous), or both. Optional. Defaults to all. Ignored when viewerId is sent.

device'all' | 'desktop' | 'mobile' | 'tablet'

Only sessions on this kind of device. desktop means anything that is not a phone or tablet. Optional. Defaults to all.

countrystring

Only sessions from this country, by name as returned by the countries endpoint, such as Canada. Optional. An empty string is ignored.

includeLegacyboolean

Include visits recorded before session tracking, which carry no timing, media or question numbers. Optional. Defaults to false.

viewerIdstring

Only sessions from this identified viewer. Optional. 32 lowercase hex characters, as returned in viewerId.

visitorIdstring

Only sessions from this browser. Optional. 16 to 64 letters, digits or dashes, as returned in visitorId.

mediaIdstring

Only sessions that opened this media file. Optional.

sort'startedAt:desc' | 'startedAt:asc' | 'activeMs:desc' | 'watchedMs:desc' | 'questions:desc'

Order of the results. Optional. Defaults to startedAt:desc.

Response

OK

status'success'

Changes