<!-- https://developers.silktide.com/v1/analytics/engagement/get-events | Analytics / Engagement -->

# List the events visitors sent, with how often and by how many

`GET /v1/results/analytics/events`

Lists every event sent in the period, one row each, most sent first: the
events your site sends with `silktide("…")`, and the ones the Silktide Script
records by itself (`page_load`, `click`, `download`, `frustration` and the
others). Send `type=custom` for only your own.

Use a row's `event` with the queries that look inside one event:
[Get event properties](https://developers.silktide.com/v1/analytics/engagement/get-event-properties.md),
[Get event property values](https://developers.silktide.com/v1/analytics/engagement/get-event-property-values.md)
and [Get event occurrences](https://developers.silktide.com/v1/analytics/engagement/get-event-occurrences.md).

Counts are numbers. The older documentation showed `occurrences` and
`visitors` as strings; read them as numbers either way.

`firstSeen` and `lastSeen` are UTC date-times such as
`2026-11-07T21:40:55Z`, not Unix timestamps. An event whose `lastSeen` is days
old may have been removed from your site by accident.

`search` matches the event's name, as sent or as shown. The table is sorted by
`occurrences` unless you send `sort`. See [Tables](https://developers.silktide.com/v1/concepts/tables.md) and,
for `view`, `period` and `filters`, [Analytics](https://developers.silktide.com/v1/analytics.md).

## Request

### Query parameters

- `view` (string, optional, matches `^(all|[1-9]\d*)$`): The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.
- `websiteId` (integer, optional, at least 1): Instead of `view`, a website whose analytics to read. The website must have Analytics set up.
- `sectionId` (integer, optional): With `websiteId`, a section of the website. Defaults to `0`, the whole website.
- `period` (string, optional): The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`. One of: `all`, `today`, `last-7-days`, `last-30-days`, `last-90-days`, `month-to-date`, `last-month`, `year-to-date`, `last-12-months`, `custom`, `-7 days`, `-30 days`, `-90 days`, `-1 month`, `month to date`, `year to date`, `-12 months`.
- `from` (string, optional): With `period=custom`, the first day, such as `2026-10-01`.
- `to` (string, optional): With `period=custom`, the last day.
- `timezone` (string, optional): The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.
- `filters` (map of strings, optional): Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.
- `columns` (string, optional): The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.
- `sort` (string, optional): The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.
- `search` (string, optional): Only rows matching this text. What it searches depends on the table, most often the URL or title.
- `page` (integer, optional, at least 1): The page of rows to return, from `1`. Defaults to `1`.
- `rowsPerPage` (integer, optional, at least 1): How many rows a page holds. Defaults to `100`.
- `type` (string, optional): `custom` for only the events your site sends, `built-in` for only those the Silktide Script records itself, such as `page_load` and `click`. Left out, both. One of: `custom`, `built-in`.
- `previousPeriod` (string, optional): `1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added. One of: `0`, `1`.

## Response

Status `200`.

- `result` (object, required): The answer.
  - `page` (integer, required, at least 1): The page returned. Not always the page asked for, when that was out of range.
  - `minPage` (integer, required, at least 1): The first page. Always `1`.
  - `maxPage` (integer, required): The last page at this `rowsPerPage`. With no rows, `0` or `1` depending on the table.
  - `numRows` (integer, required): How many rows there are across every page.
  - `rowsPerPage` (integer, required, at least 1): How many rows a page holds.
  - `rows` (list of objects, required): The rows on this page.
    - `event` (string, required): The event, by the name your site sends, or a built-in one such as `page_load`. Use it as `event` with the event's other queries and filters. Always returned, even when `columns` leaves it out.
    - `eventName` (string, required): What the event is called in Silktide: the name someone in the account gave it, else an English name for a built-in event (`Page load`), else `event`.
    - `occurrences` (integer, required): How many times it was sent in the period.
    - `visitors` (integer, required): How many visitors sent it in the period.
    - `visitorsPercent` (number, required): `visitors` as a percentage of every visitor the view or website has had, of all time. Both are estimates, so it can read over 100.
    - `isCustom` (boolean, required): `true` for an event your site sends, `false` for one the Silktide Script records itself.
    - `firstSeen` (string, required): When it was first sent in the period, in UTC, as `YYYY-MM-DDTHH:MM:SSZ`.
    - `lastSeen` (string, required): When it was last sent in the period, in UTC, as `YYYY-MM-DDTHH:MM:SSZ`.
    - `isLabeled` (boolean, required): `true` when `eventName` is a name someone in the account gave the event.
    - `previousOccurrences` (integer, optional): With `previousPeriod=1`, `occurrences` in the period before.
    - `previousVisitors` (integer, optional): With `previousPeriod=1`, `visitors` in the period before.
- `selector` (string, required): The query that answered, as its path: `/v1/results/scores`.
- `duration` (number, required): Seconds Silktide took to answer.

## Errors

| Status | Type | When |
| --- | --- | --- |
| 404 | `ModelNotFound` | No view or website with that id exists in the account, or the API key's user cannot see it. |
| 403 | `AccessDenied` | The API key's user cannot read that analytics view. |
| 200 | `ModelNotFound` | The website has no Analytics set up. The body is an error despite the status. |
| 200 | `InvalidRequest` | Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. |
| 200 | `InvalidArgument` | A filter names a key or operator Analytics does not know. The body is an error despite the status. |
| 401 | `NotLoggedIn` | No API key was sent, or it is not a key for this region. |
| 429 | `TooManyRequests` | Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats. |
| 503 | - | Silktide is busy. Retry after the number of seconds in the `Retry-After` header. |

## Access

- Permission: View analytics view (View all analytics for `view=all`)
- Plan feature: none
- Edition: Silktide 4 and Silktide 5
- Cost: free
- Stability: stable, since 1.0.0

## Example: The events your site sent in the last 30 days

```bash
curl "https://api.eu.silktide.com/v1/results/analytics/events?view=all&period=last-30-days&type=custom&rowsPerPage=2" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY"
```

Response:

```json
{
  "result": {
    "page": 1,
    "minPage": 1,
    "maxPage": 6,
    "numRows": 11,
    "rowsPerPage": 2,
    "rows": [
      {
        "event": "newsletter_signup",
        "eventName": "Newsletter sign-up",
        "occurrences": 214,
        "visitors": 198,
        "visitorsPercent": 2.61,
        "isCustom": true,
        "firstSeen": "2026-10-09T08:14:02Z",
        "lastSeen": "2026-11-07T21:40:55Z",
        "isLabeled": true
      },
      {
        "event": "added-to-basket",
        "eventName": "added-to-basket",
        "occurrences": 87,
        "visitors": 61,
        "visitorsPercent": 0.8,
        "isCustom": true,
        "firstSeen": "2026-10-09T10:02:41Z",
        "lastSeen": "2026-11-07T19:12:08Z",
        "isLabeled": false
      }
    ]
  },
  "selector": "/v1/results/analytics/events",
  "duration": 0.035
}
```