Sessions

Operations around Sessions and Session data.

Endpoints

GET /api/websites/:websiteId/sessions
GET /api/websites/:websiteId/sessions/stats
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/sessions

Gets website session details within a given time range.

Parameters

• startAt: Timestamp (in ms) of starting date.
• endAt: Timestamp (in ms) of end date.
• query: (optional string) Search text.
• page: (optional number, default 1) Determines page.
• pageSize: (optional string) Determines how many results to return.
• orderBy: (optional string) Order by column name.

Sample response

URL: https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/sessions?page=1&startAt=1725865200000&endAt=1725951599999&pageSize=20

{
  "data": [
    {
      "id": "5a45d799-e6f5-56ac-9893-fde6f769c36a",
      "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
      "hostname": "umami.is",
      "browser": "chrome",
      "os": "Windows 10",
      "device": "laptop",
      "screen": "1536x960",
      "language": "en-US",
      "country": "US",
      "subdivision1": "US-CA",
      "city": "Roseville",
      "firstAt": "2024-09-09T17:44:35Z",
      "lastAt": "2024-09-09T17:44:35Z",
      "visits": 1,
      "views": 1,
      "createdAt": "2024-09-09T17:44:35Z"
    },
    {
      "id": "753ce23b-0dab-5a33-badc-4d2239528dd9",
      "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
      "hostname": "umami.is",
      "browser": "chrome",
      "os": "Windows 10",
      "device": "desktop",
      "screen": "2560x1440",
      "language": "de-DE",
      "country": "DE",
      "subdivision1": "DE-BY",
      "city": "Munich",
      "firstAt": "2024-09-09T08:54:18Z",
      "lastAt": "2024-09-09T17:44:29Z",
      "visits": 5,
      "views": 66,
      "createdAt": "2024-09-09T17:44:29Z"
    }
  ],
  "count": 1000,
  "page": 1,
  "pageSize": 20
}

---

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

Gets summarized website session statistics.

Parameters

• startAt: Timestamp (in ms) of starting date.
• endAt: Timestamp (in ms) of end date.
• url: (optional) Name of URL.
• referrer: (optional) Name of referrer.
• title: (optional) Name of page title.
• query: (optional) Name of query.
• event: (optional) Name of event.
• host: (optional) Name of hostname.
• os: (optional) Name of operating system.
• browser: (optional) Name of browser.
• device: (optional) Name of device (ex. Mobile)
• country: (optional) Name of country.
• region: (optional) Name of region/state/province.
• city: (optional) Name of city.

Sample response

URL: https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/sessions/stats?startAt=1656679719687&endAt=1656766119687

{
  "pageviews": { "value": 3018 },
  "visitors": { "value": 847 },
  "visits": { "value": 984 },
  "countries": { "value": 537 },
  "events": { "value": 150492 }
}

• pageviews: Pages hits
• visitors: Number of unique visitors
• visits: Number of sessions
• countries: Number of unique countries
• events: Number of custom events

---

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

Gets session details for a individual session

Parameters

None

Sample response

URL: https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/sessions/a35fe227-2fe9-5147-85a0-15f0fd48faed

{
  "id": "a35fe227-2fe9-5147-85a0-15f0fd48faed",
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "hostname": "umami.is",
  "browser": "ios",
  "os": "iOS",
  "device": "mobile",
  "screen": "390x844",
  "language": "en-US",
  "country": "US",
  "subdivision1": "US-IN",
  "city": "Bloomington",
  "firstAt": "2024-09-09T18:12:01Z",
  "lastAt": "2024-09-09T18:12:08Z",
  "visits": 1,
  "views": 3,
  "events": 0,
  "totaltime": 7
}

---

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

Gets session activity for a individual session

Parameters

• startAt: Timestamp (in ms) of starting date.
• endAt: Timestamp (in ms) of end date.

Sample response

URL: https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/sessions/a35fe227-2fe9-5147-85a0-15f0fd48faed/activity?startAt=1725905521000&endAt=1725905528000

[
  {
    "createdAt": "2024-09-09T18:12:08Z",
    "urlPath": "/websites/fd4bdd56-2135-4c42-9518-55e72669f23c",
    "urlQuery": "",
    "referrerDomain": "",
    "eventId": "a154aebc-10cf-4a26-8187-c541ef0d2929",
    "eventType": 1,
    "eventName": "",
    "visitId": "609a5116-b139-5c6d-9293-fbea9b8a3b61"
  },
  {
    "createdAt": "2024-09-09T18:12:01Z",
    "urlPath": "/settings/websites",
    "urlQuery": "",
    "referrerDomain": "",
    "eventId": "92246b7b-e3e2-4c9d-b61e-fab69d993ad7",
    "eventType": 1,
    "eventName": "",
    "visitId": "609a5116-b139-5c6d-9293-fbea9b8a3b61"
  }
]

---

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

Gets session properties for a individual session

Parameters

None

Sample response

URL: https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/sessions/a35fe227-2fe9-5147-85a0-15f0fd48faed/properties

[
  {
    "websiteId": "1ccddccf-7d34-432b-84e6-e46903b2acf3",
    "sessionId": "a35fe227-2fe9-5147-85a0-15f0fd48faed",
    "dataKey": "email",
    "dataType": 1,
    "stringValue": "johndoe@gmail.com",
    "numberValue": null,
    "dateValue": null,
    "createdAt": "2024-09-09T18:12:01Z"
  },
  {
    "websiteId": "1ccddccf-7d34-432b-84e6-e46903b2acf3",
    "sessionId": "a35fe227-2fe9-5147-85a0-15f0fd48faed",
    "dataKey": "name",
    "dataType": 1,
    "stringValue": "John Doe",
    "numberValue": null,
    "dateValue": null,
    "createdAt": "2024-09-09T18:12:01Z"
  }
]

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

Gets session data counts by property name

Parameters

• startAt: Timestamp (in ms) of starting date.
• endAt: Timestamp (in ms) of end date.

Sample response

URL: https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/session-data/properties?startAt=1717916400000&endAt=1725692399999

[
  {
    "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

• startAt: Timestamp (in ms) of starting date.
• endAt: Timestamp (in ms) of end date.
• propertyName: Property name.

Sample response

URL: https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/session-data/values?startAt=1717916400000&endAt=1725692399999&propertyName=region

[
  { "value": "EU", "total": 609 },
  { "value": "US", "total": 431 }
]