事件 - Umami 中文文档

关于事件和事件数据的操作。

端点

GET /api/websites/:websiteId/events
GET /api/websites/:websiteId/events/stats
GET /api/websites/:websiteId/event-data
GET /api/websites/:websiteId/event-data/:eventId
GET /api/websites/:websiteId/event-data/events
GET /api/websites/:websiteId/event-data/fields
GET /api/websites/:websiteId/event-data/properties
GET /api/websites/:websiteId/event-data/values
GET /api/websites/:websiteId/event-data/stats
GET /api/websites/:websiteId/event-data-pivot

过滤器

所有标记为 filters 的端点现在都可以使用以下参数进行过滤。

参数	类型	描述
`path`	string	URL 名称。
`referrer`	string	引荐来源名称。
`title`	string	页面标题名称。
`query`	string	查询参数名称。
`browser`	string	浏览器名称。
`os`	string	操作系统名称。
`device`	string	设备名称（例如：移动设备）。
`country`	string	国家名称。
`region`	string	地区/州/省名称。
`city`	string	城市名称。
`language`	string	浏览器语言名称。
`hostname`	string	主机名名称。
`tag`	string	标签名称。
`event`	string	事件名称。
`distinctId`	string	distinct ID 名称。
`utmSource`	string	UTM 来源。
`utmMedium`	string	UTM 媒介。
`utmCampaign`	string	UTM 活动名称。
`utmContent`	string	UTM 内容。
`utmTerm`	string	UTM 术语。
`segment`	uuid	分群的 UUID。
`cohort`	uuid	队列的 UUID。

GET /api/websites/:websiteId/events

获取指定时间范围内网站事件的详细信息。

参数

Parameter	Type	Description
`startAt`	number	起始日期的时间戳（毫秒）。
`endAt`	number	结束日期的时间戳（毫秒）。
`search`	string	（可选）搜索文本。
`page`	number	（可选，默认 1）决定页码。
`pageSize`	number	（可选，默认 20）决定返回结果数量。
`filters`	object	可接受过滤参数。

示例响应

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "createdAt": "2025-10-15T16:26:28Z",
      "hostname": "umami.is",
      "urlPath": "/docs/api",
      "urlQuery": "",
      "referrerPath": "",
      "referrerQuery": "",
      "referrerDomain": "",
      "country": "US",
      "city": "Scott",
      "device": "desktop",
      "os": "Mac OS",
      "browser": "chrome",
      "pageTitle": "API – 文档 - Umami",
      "eventType": 1,
      "eventName": "",
      "hasData": 0
    },
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "createdAt": "2025-10-15T16:26:23Z",
      "hostname": "umami.is",
      "urlPath": "/docs/sessions",
      "urlQuery": "",
      "referrerPath": "/docs/distinct-ids",
      "referrerQuery": "",
      "referrerDomain": "umami.is",
      "country": "PL",
      "city": "Warsaw",
      "device": "desktop",
      "os": "Mac OS",
      "browser": "chrome",
      "pageTitle": "会话 – 文档 - Umami",
      "eventType": 2,
      "eventName": "login-button-header",
      "hasData": 0
    }
  ],
  "count": 2,
  "page": 1,
  "pageSize": 20
}

GET /api/websites/:websiteId/events/stats

在给定时间范围内获取聚合事件统计信息，并可选进行周期比较。

参数

参数	类型	描述
`startAt`	number	起始日期的时间戳（毫秒）。
`endAt`	number	结束日期的时间戳（毫秒）。
`compare`	string	（可选）比较周期（`prev` \| `yoy`）。
`filters`	object	（可选）可接受过滤参数。

示例响应

{
    "data": {
        "events": 753,
        "visitors": 607,
        "visits": 687,
        "uniqueEvents": 8,
        "comparison": {
            "events": 1809,
            "visitors": 1374,
            "visits": 1655,
            "uniqueEvents": 10
        }
    }
}

GET /api/websites/:websiteId/event-data

获取指定时间范围内网站的事件数据，并按事件分组。

参数

参数	类型	描述
`startAt`	number	起始日期的时间戳（毫秒）。
`endAt`	number	结束日期的时间戳（毫秒）。
`page`	number	（可选，默认 1）决定页码。
`pageSize`	number	（可选，默认 20）决定返回结果数量。
`filters`	object	可接受过滤参数。

示例响应

{
  "data": [
    {
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "eventName": "button-click",
      "eventProperties": [
        {
          "dataKey": "id",
          "stringValue": "signup-btn",
          "numberValue": null,
          "dateValue": null,
          "dataType": 1,
          "createdAt": "2025-10-15T16:26:28Z"
        },
        {
          "dataKey": "name",
          "stringValue": "Sign Up",
          "numberValue": null,
          "dateValue": null,
          "dataType": 1,
          "createdAt": "2025-10-15T16:26:28Z"
        }
      ]
    },
    {
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "eventName": "revenue-demo",
      "eventProperties": [
        {
          "dataKey": "currency",
          "stringValue": "USD",
          "numberValue": null,
          "dateValue": null,
          "dataType": 1,
          "createdAt": "2025-10-10T12:31:03Z"
        },
        {
          "dataKey": "revenue",
          "stringValue": "40.0000",
          "numberValue": 40,
          "dateValue": null,
          "dataType": 2,
          "createdAt": "2025-10-10T12:31:03Z"
        }
      ]
    }
  ],
  "count": 2,
  "page": 1,
  "pageSize": 20
}

GET /api/websites/:websiteId/event-data/:eventId

获取单个事件的 event-data

示例响应

[
  {
    "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "urlPath": "/",
    "eventName": "revenue-demo",
    "dataKey": "currency",
    "stringValue": "USD",
    "numberValue": null,
    "dateValue": null,
    "dataType": 1,
    "createdAt": "2025-10-10T12:31:03Z"
  },
  {
    "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "urlPath": "/",
    "eventName": "revenue-demo",
    "dataKey": "revenue",
    "stringValue": "40.0000",
    "numberValue": 40,
    "dateValue": null,
    "dataType": 2,
    "createdAt": "2025-10-10T12:31:03Z"
  }
]

GET /api/websites/:websiteId/event-data/events

Get the names, properties, and counts of event data.

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp for the start date (milliseconds).
`endAt`	number	Timestamp for the end date (milliseconds).
`event`	string	(Optional) Event name filter.
`filters`	object	Acceptable filter parameters.

Example response

[
  {
    "eventName": "button-click",
    "propertyName": "id",
    "dataType": 1,
    "total": 4
  },
  {
    "eventName": "button-click",
    "propertyName": "name",
    "dataType": 1,
    "total": 4
  },
  {
    "eventName": "track-product",
    "propertyName": "price",
    "dataType": 2,
    "total": 2
  }
]

GET /api/websites/:websiteId/event-data/fields

Get counts of event data properties and values within the specified time range.

Parameters

Parameter	Type	Description
`startAt`	number	Timestamp of the start date (milliseconds).
`endAt`	number	Timestamp of the end date (milliseconds).
`filters`	object	Acceptable filter parameters.

Example response

[
  {
    "propertyName": "age",
    "dataType": 2,
    "value": "33",
    "total": 1
  },
  {
    "propertyName": "age",
    "dataType": 2,
    "value": "31",
    "total": 4
  },
  {
    "propertyName": "gender",
    "dataType": 1,
    "value": "female",
    "total": 4
  },
  {
    "propertyName": "gender",
    "dataType": 1,
    "value": "male",
    "total": 1
  }
]

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

获取网站的事件名称和属性计数。

参数

Parameter	Type	Description
`startAt`	number	起始日期的时间戳（毫秒）。
`endAt`	number	结束日期的时间戳（毫秒）。
`filters`	object	可接受过滤参数。

示例响应

[
  {
    "eventName": "revenue-demo",
    "propertyName": "revenue",
    "total": 122
  },
  {
    "eventName": "revenue-demo",
    "propertyName": "currency",
    "total": 122
  }
]

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

Get the event data count for a specified event and property.

参数

Parameter	Type	Description
`startAt`	number	Timestamp of the start date (milliseconds).
`endAt`	number	Timestamp of the end date (milliseconds).
`event`	string	Event name.
`propertyName`	string	Property name.
`filters`	object	Acceptable filter parameters.

示例响应

[
  {
    "value": "Male",
    "total": 28
  },
  {
    "value": "Female",
    "total": 26
  }
]

GET /api/websites/:websiteId/event-data/stats

获取指定时间范围内网站事件、属性和记录的汇总信息。

参数

Parameter	Type	Description
`startAt`	number	起始日期的时间戳（毫秒）。
`endAt`	number	结束日期的时间戳（毫秒）。
`filters`	object	可接受过滤参数。

示例响应

[
  {
    "events": 16,
    "properties": 13,
    "records": 26
  }
]

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

以透视格式获取某个网站的事件数据，其中每一行代表一个事件及其属性，属性以并行数组的形式呈现。

参数

Parameter	Type	Description
`startAt`	number	开始日期的时间戳（毫秒）。
`endAt`	number	结束日期的时间戳（毫秒）。
`eventName`	string	要进行透视的事件名称。
`page`	number	（可选，默认 1）指定页码。
`pageSize`	number	（可选，默认 20）指定返回结果数量。
`filters`	object	可接收筛选参数。

示例响应

{
  "data": [
    {
      "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "eventName": "signup",
      "urlPath": "/register",
      "createdAt": "2025-10-15T16:26:28Z",
      "propertyKeys": ["plan", "source"],
      "propertyValues": ["pro", "organic"]
    }
  ],
  "count": 100,
  "page": 1,
  "pageSize": 20
}

事件

On this page