Endpoints

Sessions

Operations around Sessions and Session data.

Endpoints

GET /api/websites/:websiteId/sessions
GET /api/websites/:websiteId/sessions/stats
GET /api/websites/:websiteId/sessions/weekly
GET /api/websites/:websiteId/sessions/:sessionId
GET /api/websites/:websiteId/sessions/:sessionId/activity
GET /api/websites/:websiteId/sessions/:sessionId/properties
GET /api/websites/:websiteId/session-data/properties
GET /api/websites/:websiteId/session-data/values
GET /api/websites/:websiteId/session-data-pivot
GET /api/websites/:websiteId/session-data/stats

Filters#

All Endpoints marked with filters can now be filtered with the parameters below.

Parameters

Parameter	Type	Description
`path`	string	(optional) Name of URL.
`referrer`	string	(optional) Name of referrer.
`title`	string	(optional) Name of page title.
`query`	string	(optional) Name of query parameter.
`browser`	string	(optional) Name of browser.
`os`	string	(optional) Name of operating system.
`device`	string	(optional) Name of device (ex. Mobile).
`country`	string	(optional) Name of country.
`region`	string	(optional) Name of region/state/province.
`city`	string	(optional) Name of city.
`hostname`	string	(optional) Name of hostname.
`language`	string	(optional) Visitor browser language (ex. en-US).
`tag`	string	(optional) Name of tag.
`event`	string	(optional) Name of event.
`distinctId`	string	(optional) Name of distinct ID.
`utmSource`	string	(optional) UTM source.
`utmMedium`	string	(optional) UTM medium.
`utmCampaign`	string	(optional) UTM campaign name.
`utmContent`	string	(optional) UTM content.
`utmTerm`	string	(optional) UTM term.
`segment`	uuid	(optional) UUID of segment.
`cohort`	uuid	(optional) UUID of cohort.

GET /api/websites/:websiteId/sessions#

Gets website session details within a given time range.

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp (in ms) of starting date.
`endAt`	number	Timestamp (in ms) of end date.
`search`	string	(optional) Search text.
`page`	number	(optional, default 1) Determines page.
`pageSize`	number	(optional, default 20) Determines how many results to return.
`filters`	-	Can accept filter parameters.

Sample response

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "hostname": "umami.is",
      "browser": "chrome",
      "os": "Mac OS",
      "device": "desktop",
      "screen": "1800x1169",
      "language": "en-US",
      "country": "SE",
      "region": "SE-AB",
      "city": "Stockholm",
      "firstAt": "2025-10-21T13:35:51Z",
      "lastAt": "2025-10-21T15:00:09Z",
      "visits": 2,
      "views": 18,
      "createdAt": "2025-10-21T15:00:09Z"
    },
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "hostname": "umami.is",
      "browser": "safari",
      "os": "Mac OS",
      "device": "desktop",
      "screen": "1512x982",
      "language": "en-IN",
      "country": "IN",
      "region": "IN-GJ",
      "city": "Bhavnagar",
      "firstAt": "2025-10-21T14:59:47Z",
      "lastAt": "2025-10-21T14:59:48Z",
      "visits": 1,
      "views": 1,
      "createdAt": "2025-10-21T14:59:48Z"
    }
  ],
  "count": 923,
  "page": 1,
  "pageSize": 20
}

GET /api/websites/:websiteId/sessions/stats#

Gets summarized website session statistics.

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp (in ms) of starting date.
`endAt`	number	Timestamp (in ms) of end date.
`filters`	-	Can accept filter parameters.

Sample response

{
  "pageviews": {
    "value": 2924
  },
  "visitors": {
    "value": 905
  },
  "visits": {
    "value": 1050
  },
  "countries": {
    "value": 84
  },
  "events": {
    "value": 517
  }
}

pageviews: Page hits
visitors: Number of unique visitors
visits: Number of unique visits
countries: Number of unique countries
events: Number of events

GET /api/websites/:websiteId/sessions/weekly#

Get collected count of sessions by hour of weekday.

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp (in ms) of start date.
`endAt`	number	Timestamp (in ms) of end date.
`timezone`	string	Timezone (ex. America/Los_Angeles).
`filters`	-	Can accept filter parameters.

Sample response

[
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 45, 58, 57, 65, 53, 58, 135],
  [117, 124, 132, 127, 135, 142, 141, 138, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
]

GET /api/websites/:websiteId/sessions/:sessionId#

Gets session details for an individual session

Sample response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "distinctId": "",
  "browser": "chrome",
  "os": "Mac OS",
  "device": "desktop",
  "screen": "1800x1169",
  "language": "en-US",
  "country": "SE",
  "region": "SE-AB",
  "city": "Stockholm",
  "firstAt": "2025-10-21T13:35:51Z",
  "lastAt": "2025-10-21T15:00:09Z",
  "visits": 2,
  "views": 18,
  "events": 12,
  "totaltime": 1609
}

GET /api/websites/:websiteId/sessions/:sessionId/activity#

Gets session activity for an individual session

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp (in ms) of starting date.
`endAt`	number	Timestamp (in ms) of end date.

Sample response

[
  {
    "createdAt": "2025-10-21T15:00:09Z",
    "urlPath": "/blog",
    "urlQuery": "",
    "referrerDomain": "umami.is",
    "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "eventType": 1,
    "eventName": "",
    "visitId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "hasData": 0
  },
  {
    "createdAt": "2025-10-21T14:56:30Z",
    "urlPath": "/docs",
    "urlQuery": "",
    "referrerDomain": "umami.is",
    "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "eventType": 1,
    "eventName": "",
    "visitId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "hasData": 0
  },
  {
    "createdAt": "2025-10-21T14:56:30Z",
    "urlPath": "/",
    "urlQuery": "",
    "referrerDomain": "umami.is",
    "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "eventType": 1,
    "eventName": "",
    "visitId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "hasData": 0
  }
]

GET /api/websites/:websiteId/sessions/:sessionId/properties#

Gets session properties for an individual session

Sample response

[
  {
    "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "dataKey": "email",
    "dataType": 1,
    "stringValue": "bob@aol.com",
    "numberValue": null,
    "dateValue": null,
    "createdAt": "2025-10-22T02:28:17Z"
  },
  {
    "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "dataKey": "id",
    "dataType": 1,
    "stringValue": "910bfde0-21dd-4d24-804d-716035e92ddc",
    "numberValue": null,
    "dateValue": null,
    "createdAt": "2025-10-22T02:28:17Z"
  },
  {
    "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "dataKey": "name",
    "dataType": 1,
    "stringValue": "Bob Aol",
    "numberValue": null,
    "dateValue": null,
    "createdAt": "2025-10-22T02:28:17Z"
  }
]

GET /api/websites/:websiteId/session-data/properties#

Gets session data counts by property name

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp (in ms) of starting date.
`endAt`	number	Timestamp (in ms) of end date.
`propertyName`	string	(optional) Filter results to a specific property name.
`filters`	-	Can accept filter parameters.

Sample response

[
  {
    "propertyName": "id",
    "total": 1039
  },
  {
    "propertyName": "region",
    "total": 1039
  },
  {
    "propertyName": "name",
    "total": 1039
  },
  {
    "propertyName": "email",
    "total": 1039
  }
]

GET /api/websites/:websiteId/session-data/values#

Gets session data counts for a given property

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp (in ms) of starting date.
`endAt`	number	Timestamp (in ms) of end date.
`propertyName`	string	Property name.
`dataType`	number	(optional) Filter by data type (1=string, 2=number, 3=date, 4=boolean).
`filters`	-	Can accept filter parameters.

Sample response

[
  {
    "value": "EU",
    "total": 626
  },
  {
    "value": "US",
    "total": 462
  }
]

GET /api/websites/:websiteId/session-data-pivot#

Gets session data in a pivoted format, with each row representing a session and its properties as parallel arrays.

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp (in ms) of starting date.
`endAt`	number	Timestamp (in ms) of end date.
`propertyName`	string	Session property name to pivot on.
`page`	number	(optional, default 1) Determines page.
`pageSize`	number	(optional, default 20) Determines how many results to return.
`filters`	-	Can accept filter parameters.

Sample response

{
  "data": [
    {
      "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "distinctId": "user-123",
      "createdAt": "2025-10-15T16:26:28Z",
      "propertyKeys": ["plan", "role"],
      "propertyValues": ["pro", "admin"]
    }
  ],
  "count": 50,
  "page": 1,
  "pageSize": 20
}

GET /api/websites/:websiteId/session-data/stats#

Gets aggregated activity statistics for sessions grouped by a given property value.

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp (in ms) of starting date.
`endAt`	number	Timestamp (in ms) of end date.
`propertyName`	string	Property name to group by.
`filters`	-	Can accept filter parameters.

Sample response

[
  {
    "label": "pro",
    "activity": 342,
    "sessions": 89,
    "visits": 201,
    "views": 1450,
    "events": 892
  },
  {
    "label": "free",
    "activity": 158,
    "sessions": 44,
    "visits": 91,
    "views": 630,
    "events": 310
  }
]

Results are ordered by activity descending. Maximum 100 rows returned.

PreviousReports NextShare