Docs·Events
GET
/api/v1/event/analytics/web-analytics/eventsList events
Event totals for the date range, one row per event name, each with a trend line: the Event volume chart and the counts on the Events page. Rows are ranked by count unless sortBy and sortDir say otherwise.
By default the list holds the events you send yourself (with track() or from a server, payments included) and the automatic scroll event. Set allEventTypes=true to also count page views, session ends and outbound link clicks, named by type: page_view, session_end and link_click. The Events page sends it, so its chart agrees with the feed beside it.
Keys: an account key. Getting started explains both kinds.
Parameters
| Prop | In | Type | Notes |
|---|---|---|---|
contactListId | query | string | The id of the audience (the tracked site) to read, a UUID: anything else returns a 400. You must be a member of the workspace the audience belongs to, or the call returns a 401. An id that matches no audience is not an error: the call returns no data. |
startDate | query | string | Start of the date range, read as UTC: a date such as 2026-09-01 (from midnight), or an exact time such as 2026-09-01T09:30:00Z. Use one of these two forms. |
endDate | query | string | End of the date range, read as UTC. A date such as 2026-09-30 includes that whole day; an exact time such as 2026-09-30T18:00:00Z ends the range right before that moment. If the workspace has gone past its plan's event allowance this billing period, the range is cut short at the moment the allowance ran out. |
granularity | query | Granularity | Bucket size of trendline. Bucket size: minute, hour, day, week or month, in UTC. A bucket is one such interval; weeks start on Monday and months on the 1st. minute needs a range of 25 hours or less and hour one of 8 days or less, or the call returns a 400. |
page | query | number | Page number, starting at 0. |
pageSize | query | number | Rows per page. |
search? | query | string | Keep only event names that contain this text, ignoring case. |
filter? | query | string | Narrows the results: a URL-encoded JSON array of conditions, each [key, values, operator], where a missing operator means is. Example: [["country",["US","GB"]],["page",["/pricing"],"startsWith"]] keeps visits from the US or the UK that viewed a page starting with /pricing. Every condition must match, and each key can appear once (a second condition on the same key replaces the first). A condition matches any of its values, except that isNot, notContains and notRegex rule out all of them. Operators: is and isNot (exact), contains, notContains, startsWith and endsWith (ignoring case), regex and notRegex (RE2 syntax, so no lookarounds; a pattern that does not compile returns a 400), and isNull and isNotNull (the value is not set, or is set; send [] as the values). Keys: channel, referrer_source, referrer, utm_source, utm_medium, utm_campaign, utm_term, utm_content, country (a two-letter code), region, city, browser, browser_version, os, os_version, screen_size (Desktop, Mobile or Tablet), hostname, entry_page, exit_page, page and event_name (visits that viewed such a page or sent such an event), identified (["true"] or ["false"]), goal_id (people who completed the goal in the range) and cohort_id (members of a segment). The last two take ids and only is or isNot. Unknown keys, and a filter that is not valid JSON, are ignored rather than refused. |
sortBy? | query | EventSortBy | The column to rank by: count (the default, also accepted as visitors), revenue, uniqueVisitors or eventName. |
sortDir? | query | SortDirection | desc (the default) puts the highest value first, or Z to A for a name or path; asc the reverse. The order covers every page, not just the one returned. |
allEventTypes? | query | boolean | true counts every event type: as well as your own events and scroll, page views (page_view), session ends (session_end) and outbound link clicks (link_click). Off by default. |
Response
| Prop | Type | Notes |
|---|---|---|
content | EventAnalyticsRow[] | One row per event name. |
size | number | The pageSize you asked for. |
page | number | The page you asked for, counted from 0. |
totalItems | number | Rows across all pages. |
totalPages | number | totalItems divided by size, rounded up. |
Each item in content
| Prop | Type | Notes |
|---|---|---|
eventName | string | The event's name. Built-in events read their type: scroll, and with allEventTypes also page_view, session_end and link_click. |
count | number | How many times it happened in the range. |
uniqueVisitors | number | Distinct visitors who sent it. |
trendline | object[] | { date, count } for every bucket of the range, oldest first, with 0 in empty buckets. date is the start of the bucket, in the same form as the timeseries endpoints use. |
revenue | number | Everything the visitors who sent this event paid in the range, net, in the audience's reporting currency (Settings → Revenue). A visitor counts under every event they sent, so rows add up to more than the total. |
Request
curl 'https://app.spreelytics.com/api/v1/event/analytics/web-analytics/events?contactListId=…&startDate=…&endDate=…&granularity=…&page=…&pageSize=…' \
-H 'Authorization: Bearer YOUR_API_KEY'
const url = new URL('https://app.spreelytics.com/api/v1/event/analytics/web-analytics/events');
url.searchParams.set('contactListId', '…');
url.searchParams.set('startDate', '…');
url.searchParams.set('endDate', '…');
url.searchParams.set('granularity', '…');
url.searchParams.set('page', '…');
url.searchParams.set('pageSize', '…');
const res = await fetch(url, {
headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const data = await res.json();
import requests
res = requests.get(
"https://app.spreelytics.com/api/v1/event/analytics/web-analytics/events",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"contactListId": "…", "startDate": "…", "endDate": "…", "granularity": "…", "page": "…", "pageSize": "…"},
)
data = res.json()
Response
{
"content": [
{
"eventName": "string",
"count": 0,
"uniqueVisitors": 0,
"trendline": [
{
"count": null,
"date": null
}
],
"revenue": 0
}
],
"size": 0,
"page": 0,
"totalItems": 0,
"totalPages": 0
}