文档指南API 参考Cloudv2

会话

有关会话及会话数据的操作。

接口

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 的接口现在均可使用以下参数进行过滤。

参数

参数类型说明
pathstring（可选）URL 名称。
referrerstring（可选）引用来源名称。
titlestring（可选）页面标题名称。
querystring（可选）查询参数名称。
browserstring（可选）浏览器名称。
osstring（可选）操作系统名称。
devicestring（可选）设备名称（例如 Mobile）。
countrystring（可选）国家名称。
regionstring（可选）地区/州/省名称。
citystring（可选）城市名称。
hostnamestring（可选）主机名名称。
languagestring（可选）访客浏览器语言（例如 en-US）。
tagstring（可选）标签名称。
eventstring（可选）事件名称。
distinctIdstring（可选）distinct ID 名称。
utmSourcestring（可选）UTM 来源。
utmMediumstring（可选）UTM 媒介。
utmCampaignstring（可选）UTM 活动名称。
utmContentstring（可选）UTM 内容。
utmTermstring（可选）UTM 关键词。
segmentuuid（可选）分群 UUID。
cohortuuid（可选）队列 UUID。

GET /api/websites/:websiteId/sessions

获取指定时间范围内的网站会话详情。

参数

参数类型说明
startAtnumber开始日期的时间戳（毫秒）。
endAtnumber结束日期的时间戳（毫秒）。
searchstring（可选）搜索文本。
pagenumber（可选，默认 1）确定页码。
pageSizenumber（可选，默认 20）确定返回多少结果。
filters-可接受过滤参数。

示例响应

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

获取汇总的网站会话统计数据。

参数

参数类型说明
startAtnumber开始日期的时间戳（毫秒）。
endAtnumber结束日期的时间戳（毫秒）。
filters-可接受过滤参数。

示例响应

{
  "pageviews": {
    "value": 2924
  },
  "visitors": {
    "value": 905
  },
  "visits": {
    "value": 1050
  },
  "countries": {
    "value": 84
  },
  "events": {
    "value": 517
  }
}
  • pageviews: 页面浏览量
  • visitors: 独立访客数
  • visits: 独立访问次数
  • countries: 独立国家/地区数
  • events: 事件数

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

按周中小时统计会话数。

参数

参数类型说明
startAtnumber开始日期的时间戳（毫秒）。
endAtnumber结束日期的时间戳（毫秒）。
timezonestring时区（例如 America/Los_Angeles）。
filters-可接受过滤参数。

示例响应

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

获取单个会话的详细信息

示例响应

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

获取单个会话的会话活动

参数

参数类型说明
startAtnumber开始日期的时间戳（毫秒）。
endAtnumber结束日期的时间戳（毫秒）。

示例响应

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

获取单个会话的会话属性

示例响应

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

按属性名称统计会话数据数量。

参数

参数类型说明
startAtnumber开始日期的时间戳（毫秒）。
endAtnumber结束日期的时间戳（毫秒）。
propertyNamestring（可选）将结果筛选为特定的属性名称。
filters-可以接受筛选参数。

示例响应

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

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

获取指定属性的会话数据数量。

参数

参数类型说明
startAtnumber开始日期的时间戳（毫秒）。
endAtnumber结束日期的时间戳（毫秒）。
propertyNamestring属性名称。
dataTypenumber（可选）按数据类型筛选（1=字符串，2=数字，3=日期，4=布尔值）。
filters-可接受筛选参数。

示例响应

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

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

以透视格式获取会话数据，每一行表示一个会话及其属性的并行数组。

参数

ParameterTypeDescription
startAtnumber开始日期的时间戳（毫秒）。
endAtnumber结束日期的时间戳（毫秒）。
propertyNamestring要进行透视的会话属性名称。
pagenumber（可选，默认值 1）决定页码。
pageSizenumber（可选，默认值 20）决定返回多少结果。
filters-可接受筛选参数。

示例响应

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

获取按给定属性值分组的会话汇总活动统计。

参数

参数类型描述
startAtnumber开始日期的时间戳（毫秒）。
endAtnumber结束日期的时间戳（毫秒）。
propertyNamestring要按其分组的属性名。
filters-可接受筛选参数。

示例响应

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

结果按 activity 降序排列。最多返回 100 行。

报告

Previous Page

分享

Next Page

On this page

过滤器GET /api/websites/:websiteId/sessionsGET /api/websites/:websiteId/sessions/statsGET /api/websites/:websiteId/sessions/weeklyGET /api/websites/:websiteId/sessions/:sessionIdGET /api/websites/:websiteId/sessions/:sessionId/activityGET /api/websites/:websiteId/sessions/:sessionId/propertiesGET /api/websites/:websiteId/session-data/propertiesGET /api/websites/:websiteId/session-data/valuesGET /api/websites/:websiteId/session-data-pivotGET /api/websites/:websiteId/session-data/stats