Docs·Web analytics
GET
/api/v1/event/analytics/web-analytics/summaryGet the headline numbers
The numbers in the strip at the top of the Overview page, for one date range: Visitors, sessions, Bounce rate, Session Time, pages per session, Revenue, Conversion rate and Revenue/visitor, each with its change against the period of the same length right before it. It also carries the live Online count.
Sessions and visitors are counted by when the session started. A visitor is one browser, so a person on two devices counts twice. A session is a bounce when it had one page and no interactions (your own events or link clicks; the automatic scroll event does not count), and it is only marked as one when it ends. Sessions that have not ended yet count as 0 in avgSessionDuration.
Revenue is net of refunds, in the audience's reporting currency (set in Settings → Revenue). Conversion here means a payment above 0: conversionRate is the share of visitors who paid, so a free trial's first invoice of 0 does not count. Goal conversions are on Get goal results.
With a filter, revenue and conversions count only payments from people who had a matching session in the range. A payment sent from a server counts when it names the buyer's visitor id or an email we already know, and drops out when it names neither.
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. |
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. |
Response
| Prop | Type | Notes |
|---|---|---|
uniqueVisitors | number | Distinct visitors with a session that started in the range. |
sessions | number | Sessions that started in the range. |
bounceRate | number | Bounced sessions as a percentage of sessions: 0 to 100, two decimals. |
newVisitors | number | Visitors whose first session ever started inside the range. |
returningVisitors | number | Visitors whose first session ever started before the range. |
avgSessionDuration | number | Average session length in milliseconds, as a whole number. |
pagesPerSession | number | Average page views per session, two decimals. |
revenue | number | Net revenue in the range, in the reporting currency, in whole units with two decimals (12.5 is 12.50, not cents). |
revenuePerVisitor | number | revenue divided by uniqueVisitors, two decimals. |
conversionRate | number | People who made a payment above 0 in the range, divided by uniqueVisitors: a fraction from 0 to 1 with four decimals, so 0.0325 is 3.25%. A payment sent from a server counts when it names the buyer's visitor id or an email we already know. |
onlineVisitors | number | People with activity in the last 5 minutes, whatever the date range. Someone on two tabs or two devices counts once. It has no entry in changes. |
retentionRate | number | returningVisitors divided by uniqueVisitors: a fraction from 0 to 1 with four decimals. This is not the grid from /web-analytics/retention. |
previousPeriod | object | The range the changes compare against, as { startDate, endDate }: the same length, ending right before startDate, in the form you sent (dates with an included end day, or exact times with an excluded end). |
changes | object | Percentage change of each number above against previousPeriod, two decimals: 12.5 means up 12.5%. Rates change relatively too, so a bounce rate going from 40 to 50 reads 25, not 10. Null when the previous value was 0. |
Request
curl 'https://app.spreelytics.com/api/v1/event/analytics/web-analytics/summary?contactListId=…&startDate=…&endDate=…' \
-H 'Authorization: Bearer YOUR_API_KEY'
const url = new URL('https://app.spreelytics.com/api/v1/event/analytics/web-analytics/summary');
url.searchParams.set('contactListId', '…');
url.searchParams.set('startDate', '…');
url.searchParams.set('endDate', '…');
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/summary",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"contactListId": "…", "startDate": "…", "endDate": "…"},
)
data = res.json()
Response
{
"uniqueVisitors": 0,
"sessions": 0,
"bounceRate": 0,
"newVisitors": 0,
"returningVisitors": 0,
"avgSessionDuration": 0,
"pagesPerSession": 0,
"revenue": 0,
"revenuePerVisitor": 0,
"conversionRate": 0,
"onlineVisitors": 0,
"retentionRate": 0,
"previousPeriod": {
"endDate": "string",
"startDate": "string"
},
"changes": {
"retentionRate": 0,
"conversionRate": 0,
"revenuePerVisitor": 0,
"revenue": 0,
"pagesPerSession": 0,
"avgSessionDuration": 0,
"returningVisitors": 0,
"newVisitors": 0,
"bounceRate": 0,
"sessions": 0,
"uniqueVisitors": 0
}
}