# 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](/docs/api#start) 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**

```bash
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"}'
```

**CLI**

```bash
clearsaga realtime snapshot --input '{"siteId":"site_abc123def456"}'
```

**MCP**

```text
Tool: realtime_snapshot
Arguments: {"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**

```bash
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}'
```

**CLI**

```bash
clearsaga realtime visitor --input '{"siteId":"site_abc123def456","visitId":1}'
```

**MCP**

```text
Tool: realtime_visitor
Arguments: {"siteId":"site_abc123def456","visitId":1}
```

Run `clearsaga help realtime visitor` for one flag per field.