> ## Documentation Index
> Fetch the complete documentation index at: https://docs.betterumami.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Retrieve a paginated log of individual pageviews and custom events for a website, with full session context, newest first. Supports filtering and search.

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

**Authorization** `string` *required*

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

### Path Parameters

**websiteId** `string` *required*

The unique UUID of the website to query.

### Query Parameters

#### Pagination

**page** `integer`

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

**pageSize** `integer`

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

**maxResults** `integer`

Hard cap on the total number of results returned.

**search** `string`

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

#### Date Range

**startAt** `number`

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

**endAt** `number`

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

**startDate** `string`

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

**endDate** `string`

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

**timezone** `string`

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

**unit** `string`

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

**compare** `string`

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

#### Filters

**eventType** `integer`

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

**event** `string`

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

**path** `string`

Filter by URL path.

**referrer** `string`

Filter by referring URL.

**title** `string`

Filter by page title.

**query** `string`

Filter by URL query string.

**os** `string`

Filter by visitor operating system.

**browser** `string`

Filter by visitor browser.

**device** `string`

Filter by device category.

**country** `string`

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

**region** `string`

Filter by visitor region.

**city** `string`

Filter by visitor city.

**language** `string`

Filter by browser language.

**utmSource** `string`

Filter by UTM source.

**utmMedium** `string`

Filter by UTM medium.

**utmCampaign** `string`

Filter by UTM campaign name.

**utmContent** `string`

Filter by UTM content.

**utmTerm** `string`

Filter by UTM term.

**tag** `string`

Filter by a tag attached to tracked activity.

**hostname** `string`

Filter by hostname.

**distinctId** `string`

Filter by a custom visitor identifier.

**excludeBounce** `string`

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

**segment** `string`

UUID of a saved segment to apply.

**cohort** `string`

UUID of a saved cohort to filter by.

**match** `string`

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

## Response

**200 – Success**

**count** `integer` *required*

Total number of event records matching the query.

**data** `WebsiteEvent[]` *required*

Array of event records, newest first.

**data\[].id** `string`

Unique UUID of this event record.

**data\[].websiteId** `string`

UUID of the website this event belongs to.

**data\[].sessionId** `string`

UUID of the session in which this event occurred.

**data\[].createdAt** `string`

ISO 8601 timestamp when this event was recorded.

**data\[].urlPath** `string`

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

**data\[].urlQuery** `string`

URL query string at the time of the event.

**data\[].referrerDomain** `string`

Domain of the referring page.

**data\[].pageTitle** `string`

Title of the page at the time of the event.

**data\[].hostname** `string`

Hostname on which the event was recorded.

**data\[].eventType** `integer`

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

**data\[].eventName** `string`

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

**data\[].distinctId** `string`

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

**page** `integer` *required*

Current page number.

**pageSize** `integer` *required*

Number of records per page.

**isCapped** `boolean`

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

```json 200 Response theme={null}
{
  "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

```bash theme={null}
# 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>'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.