List Website Events — GET /api/websites/{websiteId}/events

Use this endpoint to page through the raw event log for a website. Each record represents either a pageview (eventType: 1) or a custom event (eventType: 2) and includes the full session context: URL path, query string, referrer domain, page title, event name, and the optional distinctId you set for logged-in visitors. Results are returned newest first and are paginated. GET /api/websites/{websiteId}/events

Request

Headers

string

required

Bearer token. Pass your API key: Authorization: Bearer <api-key>

Path Parameters

string

required

The unique UUID of the website to query.

Query Parameters

Pagination

integer

Page number to return, starting at 1. Defaults to 1.

integer

Number of event records per page. Defaults to server-defined limit.

integer

Hard cap on the total number of results returned.

string

Search string applied across event details such as URL path, event name, and page title.

Date Range

number

Start of the date range as a Unix timestamp in milliseconds.

number

End of the date range as a Unix timestamp in milliseconds.

string

Start of the date range as an ISO 8601 date or datetime.

string

End of the date range as an ISO 8601 date or datetime.

string

IANA time zone for date interpretation, e.g. America/Los_Angeles.

string

Time interval used to group results: minute, hour, day, month, or year.

string

Comparison period: prev for the immediately preceding period or yoy for the same period one year ago.

Filters

integer

Filter by event type: 1 for pageviews, 2 for custom events.

string

Filter by custom event name, e.g. "signup".

string

Filter by URL path.

string

Filter by referring URL.

string

Filter by page title.

string

Filter by URL query string.

string

Filter by visitor operating system.

string

Filter by visitor browser.

string

Filter by device category.

string

Filter by ISO 3166-1 alpha-2 country code.

string

Filter by visitor region.

string

Filter by visitor city.

string

Filter by browser language.

string

Filter by UTM source.

string

Filter by UTM medium.

string

Filter by UTM campaign name.

string

Filter by UTM content.

string

Filter by UTM term.

string

Filter by a tag attached to tracked activity.

string

Filter by hostname.

string

Filter by a custom visitor identifier.

string

Set to any non-empty value to exclude events from single-pageview visits.

string

UUID of a saved segment to apply.

string

UUID of a saved cohort to filter by.

string

Filter combination logic: all (AND, default) or any (OR).

Response

200 – Success

integer

required

Total number of event records matching the query.

WebsiteEvent[]

required

Array of event records, newest first.

string

Unique UUID of this event record.

string

UUID of the website this event belongs to.

string

UUID of the session in which this event occurred.

string

ISO 8601 timestamp when this event was recorded.

string

URL path where the event occurred, e.g. /checkout.

string

URL query string at the time of the event.

string

Domain of the referring page.

string

Title of the page at the time of the event.

string

Hostname on which the event was recorded.

integer

Event type: 1 for a pageview, 2 for a custom event.

string

Name of the custom event, e.g. "add_to_cart". Empty for pageviews.

string

Custom identifier assigned to the visitor by your application, if set.

integer

required

Current page number.

integer

required

Number of records per page.

boolean

true if the result set was truncated by the maxResults limit.

200 Response

{
  "count": 2348,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "websiteId": "b8d3a1f0-1c2d-4e5f-8a9b-0c1d2e3f4a5b",
      "sessionId": "d4e5f6a7-b8c9-0123-def0-123456789abc",
      "createdAt": "2024-08-07T14:23:11Z",
      "urlPath": "/checkout",
      "urlQuery": "?plan=pro",
      "referrerDomain": "google.com",
      "pageTitle": "Upgrade to Pro – Betterumami",
      "hostname": "betterumami.com",
      "eventType": 2,
      "eventName": "upgrade_click",
      "distinctId": "user_98765"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
      "websiteId": "b8d3a1f0-1c2d-4e5f-8a9b-0c1d2e3f4a5b",
      "sessionId": "e5f6a7b8-c9d0-1234-ef01-23456789abcd",
      "createdAt": "2024-08-07T14:21:55Z",
      "urlPath": "/pricing",
      "urlQuery": "",
      "referrerDomain": "twitter.com",
      "pageTitle": "Pricing – Betterumami",
      "hostname": "betterumami.com",
      "eventType": 1,
      "eventName": "",
      "distinctId": ""
    }
  ],
  "page": 1,
  "pageSize": 50,
  "isCapped": false
}

Code Sample

# List the last 50 custom events for a website
curl -X GET 'https://api.umami.is/v1/websites/b8d3a1f0-1c2d-4e5f-8a9b-0c1d2e3f4a5b/events?eventType=2&page=1&pageSize=50&startAt=1722470400000&endAt=1723075200000' \
  -H 'Authorization: Bearer <api-key>'

Overview

Websites

Stats & Events

Node Client

List Website Events — GET /api/websites/{websiteId}/events

Request

Headers

Path Parameters

Query Parameters

Date Range

Filters

Response

Code Sample

​Request

​Headers

​Path Parameters

​Query Parameters

​Pagination

​Date Range

​Filters

​Response

​Code Sample

Request

Headers

Path Parameters

Query Parameters

Pagination

Date Range

Filters

Response

Code Sample