Skip to content

API reference Realtime

API reference

Realtime

The API operations about realtime, each with its input, its output and an example.

The operations about realtime. Each one is a POST with a JSON object as its body: Making a request has the rules they share.

Realtime snapshot #

POST /api/v1/realtime.snapshot · Read

What is happening on one site at this moment: visitors online (a hit in the last two minutes), visitors, page views and custom events of the last 30 minutes, where those visitors are, the newest hits, and the countries, pages and referring sites with the most recent visitors. Get the siteId from sites.list first. It takes nothing but the site: no range, no comparison and no filters. Each call is a fresh picture, so call it again for newer numbers, no more often than every few seconds. The lists are capped (50 hits per list, 100 visitors) and there is no paging. Places are city centres. No row carries a visitor id. For the workspace's own callers each visitor row carries a visit number, a handle for realtime.visitor and nothing else, and a seed for a generated name that changes every day. For numbers over a longer period call overview.kpis. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Field Type Required Description
siteId string required The site id, from sites.list.

Output #

Field Type Present Description
serverNow number always The clock the snapshot was taken at, milliseconds since 1970 UTC.
liveWindowSec number always How many seconds back a visitor counts as online.
recentWindowMin number always How many minutes back the window numbers, the map, the lists and the top tables reach.
online number always Visitors with a page view or custom event in the last liveWindowSec seconds.
window object always Visitors, page views and custom events of the last recentWindowMin minutes.
points array of object always Where recent visitors are, for a map: one point per place with its latitude, longitude, the number of visitors (count), the two-letter country code, when known the region and city, and the visit numbers of the visitors there (visits). The code is in upper case (US), while the country filter and the keys of overview.breakdown take it in lower case (us). Places are city centres, never an address.
locations number always The number of distinct places among the recent visitors.
activity object always The newest hits, newest first, at most 50 per list: all of them, page views only, and custom events only. Each has its time ts in milliseconds since 1970 UTC, its kind (pageview, custom or 404), the event name for a custom event and the path.
visitors array of object always The recent visitors by when they were last seen, newest first, at most 100: the time, kind, event name and path of their latest hit, and their two-letter country code or null. The code is in upper case (US), while the country filter and the keys of overview.breakdown take it in lower case (us). Under member: the visit number (the handle for realtime.visitor), the city, device, browser, system and source of the visit, and the seed of a generated name that changes every day. A row carries no visitor id.
top object always The countries, pages and referring sites with the most recent visitors. The code of a country is two letters in upper case (US), while the country filter and the keys of overview.breakdown take it in lower case (us). A country row with a null code is the visitors whose country is unknown.

Example #

curl -s -X POST https://clearsaga.com/api/v1/realtime.snapshot \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

Run clearsaga help realtime snapshot for one flag per field.

Live visitor #

POST /api/v1/realtime.visitor · Read

One visit that is on the site right now, as the live visitor card of the Realtime page shows it: whether it is online, when it began and was last seen, its country, region and city, its device, system and browser, where it came from, the page it is on, the page views and custom events of this visit, and how many visits the same daily visitor code made today. Get the siteId from sites.list and the visitId from realtime.snapshot first: visitors[].member.visitId or points[].visits[]. It also answers how likely visitors like this one are to complete one of the site's conversion goals (likelihood), worked out from the last 30 days of the site, and, when the site has orders linked to visits and the caller may see revenue, what such a visit is worth on average (value). The answer names no person: a visit number is a counter, the name and picture the dashboard draws come from a seed that changes every day, and the answer never carries the daily visitor code or the cookie id. When the site remembers returning visitors and this visit is linked to one, remembered holds the key of that remembered visitor (the visitorKey for visitors.get), how many visits are remembered for them and when they were first remembered; otherwise remembered is null. A visit is only answered while it is on the live list, about 30 minutes after its last hit; afterwards, and for a number that was never a visit of this site, the answer is 404 not_found. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Field Type Required Description
siteId string required The site id, from sites.list.
visitId integer, at most 9007199254740991 required The visit number from realtime.snapshot: visitors[].member.visitId or points[].visits[]. It is only valid while the visit is on the live list, about 30 minutes after its last hit; afterwards the answer is 404.

Output #

Field Type Present Description
serverNow number always The clock the answer was taken at, milliseconds since 1970 UTC.
visitId number always The visit number that was asked for.
online boolean always True when the visit had a hit in the last two minutes.
lastSeen number always The time of the latest hit, milliseconds since 1970 UTC.
startedAt number always When the visit began, milliseconds since 1970 UTC.
persona string always Ten hex characters: the seed of the generated name and picture, the same as on the snapshot row. It changes every day.
place object always Where the visit came from: the two-letter country code in upper case, the region and the city, each null when unknown. A city, never an address.
device object always The kind of device, the browser and the system.
source object always How the visit arrived: the referring site (null for a direct visit), the channel, the AI tool when one sent the visitor, and the source and campaign of a tagged link.
currentPath string always The path of the latest hit.
pages array of object always The page views of this visit, oldest first: the time in milliseconds since 1970 UTC and the path. At most 50; of a longer visit, the newest.
events array of object always The custom events of this visit, oldest first: the time and the event name. At most 50; of a longer visit, the newest.
visitsToday number always The visits the same daily visitor code made today (UTC), this one included.
likelihood object always How likely visitors like this one are to complete one of the conversion goals that are switched on, from the last 30 days of this site: arithmetic over how often visitors with the same device, system, browser, country and channel converted. state says which of three answers this is: converted, ready or not_enough_data.
value object | null always What a visit like this one is worth on average, from orders linked to visits. Null without at least 20 visitors with a linked order in the window, and always null for a caller who may not see revenue.
remembered object | null always The remembered visitor this visit is linked to. Null while the site does not remember returning visitors, and for a visit that is not linked to one.

Example #

curl -s -X POST https://clearsaga.com/api/v1/realtime.visitor \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","visitId":1}'

Run clearsaga help realtime visitor for one flag per field.