Reference

List sessions

Return a list of website sessions.

URL

GET /v1/sessions

Requirements

Type	Description
scopes	`users.sessions:read`
tokens	Personal Access Token

Parameters

Name	Type	Required	Descriptions
email	`string`	false	The email address that you have associated with a session via identify.
visitor_id	`string`	false	The visitor ID.
page	`string`	false	The number of page to start with (default 0, max 10000).
size	`string`	false	The number of page's size (default 25, max 100).
date_from	`string` \| `RelativeDateString`	false	ISO 8601 string or RelativeDateString. For RelativeDateString see table below for possible values.
date_to	`string` \| `RelativeDateString`	false	ISO 8601 string or RelativeDateString. For RelativeDateString see table below for possible values.
tz	`string`	false	IANA timezone. Default Europe/London if RelativeDateString is applied.

For date range parameters if you would use different time zone than UTC you must encode + character with %2b.

RelativeDateString spec.

Name	Type	Descriptions
TODAY	`string`	Today since midnight.
YESTERDAY	`string`	Yesterday since midnight.
BEGINNING_OF_WEEK	`string`	Nearest monday since midnight.
BEGINNING_OF_MONTH	`string`	1st of the month since midnight.
BEGINNING_OF_PREV_MONTH	`string`	Previous 1st of the month since midnight.
TODAY-7DAYS	`string`	Exact 7 days ago since midnight.
TODAY-30DAYS	`string`	Exact 30 days ago since midnight.

Example requests

Get all sessions that match email criteria.

curl -X GET \
  https://api.livesession.io/v1/sessions?email=john@example.com \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer {YOUR_PERSONAL_ACCESS_TOKEN}'

Get all sessions that match email and older than Tue, 05 Oct 2021 17:56:02 +0200.

curl -X GET \
  https://api.livesession.io/v1/sessions?email=john@example.com&date_from=2021-10-04T12:10:10%2b02:00 \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer {YOUR_PERSONAL_ACCESS_TOKEN}'

Get all sessions from today in Europe/Warsaw time zone.

curl -X GET \
  https://api.livesession.io/v1/sessions?date_from=TODAY&tz=Europe/Warsaw \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer {YOUR_PERSONAL_ACCESS_TOKEN}'

Get all sessions that match email and between Tue, 05 Oct 2021 08:10:10 +0000 and Tue, 05 Oct 2021 11:10:10 +0000.

curl -X GET \
  https://api.livesession.io/v1/sessions?email=john@example.com&date_from=2021-10-05T08:10:10Z&date_to=2021-10-05T11:10:10Z \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer {YOUR_PERSONAL_ACCESS_TOKEN}'

Status codes

Code	Status	Description
200	OK	JSON body

Example response

{
  "total": 6,
  "page": {
    "num": 0,
    "size": 10
  },
  "sessions": [
    {
      "id": "9a000f77-8b3e-41a5-6443-b92ac1ec2538",
      "website_id": "f12e633c",
      "session_url": "https://app.livesession.io/app/sessions/e836228e-e633-4ba3-6859-dcc57fc370bb/9a000f77-8b3e-41a5-6443-b92ac1ec2538",
      "creation_timestamp": 1621514771785,
      "duration": 978750,
      "end_timestamp": 1621515750535,
      "active_time": 9473,
      "end_url": "https://livesession.io",
      "expiration_timestamp": 1621517550535,
      "last_event_timestamp": 1621515750535,
      "product": "",
      "device": "Desktop",
      "tags": null,
      "seen": true,
      "referrer": "",
      "start_url": "https://livesession.io",
      "visitor_first_session": true,
      "engagment_score": 0.686962962962963,
      "visitor": {
        "id": "e836228e-e633-4ba3-6859-dcc57fc370bb",
        "ip": "",
        "geolocation": {
          "country_code": "",
          "city": "",
          "region": ""
        },
        "last_session_timestamp": 1621514771785,
        "first_session_timestamp": 1621514771785
      },
      "resolution": {
        "height": 1080,
        "width": 3840,
        "resolution": ""
      },
      "os": {
        "name": "Linux",
        "version": ""
      },
      "browser": {
        "description": "Chrome 90.0.4430.212 on Linux 64-bit",
        "name": "Chrome",
        "version": "90.0.4430.212"
      },
      "utm": {
        "source": "",
        "medium": "",
        "campaign": "",
        "term": "",
        "content": ""
      },
      "page_views_statistics": {
        "count": 1
      },
      "events_statistics": {
        "clicks": 3,
        "error_clicks": 0,
        "rage_clicks": 0,
        "error_logs": 0
      }
    }
  ]
}