Visitors API

These endpoints use your API key and return the same data as the Visitors page in the dashboard.

import { KerAbieClient } from '@kerabie/sdk';

const kerabie = new KerAbieClient({ apiKey: process.env.KERABIE_API_KEY });

Visitor history is recorded when someone opens your chat widget and is kept for 30 days. A visitor who never sends a message is still recorded; they just have no contact or conversation.

List visitors

GET /v1/visitors

const { data, meta } = await kerabie.visitors.list({ status: 'online' });

Query param	Description
`status`	`all` (default), `online`, `offline`, `blocked` or `allowed`.
`search`	Case-insensitive match on name, email, IP, city or page.
`country`	Two-letter country code, e.g. `NG`.
`days`	How far back to look. Default `7`, maximum `30`.
`page`, `limit`	Pagination. `limit` defaults to 20, maximum 100.

{
  "data": [
    {
      "sessionId": "sess_8f2c1d",
      "name": "Chidi Okafor",
      "email": "chidi@palmex.com",
      "phone": "+234 803 555 0142",
      "country": "NG",
      "city": "Lagos",
      "ip": "102.89.34.12",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) …",
      "currentPage": "/pricing",
      "visitCount": 14,
      "firstSeenAt": "2026-09-28T09:10:00.000Z",
      "lastSeenAt": "2026-10-05T10:52:00.000Z",
      "conversationId": 101,
      "status": "online"
    }
  ],
  "meta": { "total": 43, "page": 1, "limit": 20, "pages": 3, "truncated": false }
}

Field notes

status is derived from your IP rules and wins over presence: a visitor on the allowlist reads allowed even while online, and a blocked IP reads blocked. A blocklist match wins over an allowlist match, as it does when the visitor connects.
status=blocked and status=allowed match IP ranges (for example 203.0.113.0/24) as well as exact IPs. They are checked against the 1,000 most recent matching visitors, and meta.truncated is true when that limit was reached.
ip is null when your organisation hides visitor IPs in its privacy settings. Blocking and allowing still apply to the real address.
visitCount goes up by one when a visitor comes back after being away for 30 minutes or more. Reloading a page or coming back quickly does not count.
name and email come from the contact record if the visitor has chatted, otherwise from what they told the widget.
currentPage is the page they are on right now for online visitors, otherwise the last page they were on.

Overview numbers

GET /v1/visitors/overview

const overview = await kerabie.visitors.getOverview();

{
  "online": 3,
  "countries": 9,
  "returning": 7,
  "blockedIps": 1,
  "topCountries": [{ "country": "NG", "count": 5 }, { "country": "GB", "count": 4 }]
}

Field	Meaning
`online`	Visitors on the site right now (always live).
`countries`	Distinct countries among visitors in the last 24 hours.
`returning`	Visitors in the last 24 hours who have visited more than once.
`blockedIps`	Active block rules.
`topCountries`	Up to five countries by visitor count in the last 24 hours, most first.

The last-24-hours numbers are cached for up to 30 seconds.

Export to CSV

GET /v1/visitors/export

const { filename, csv, count, truncated } = await kerabie.visitors.export({ status: 'blocked' });

Accepts status, search, country and days as above.

At most 5,000 visitors are returned; truncated is true if more matched.
The IP column is empty when your organisation hides visitor IPs.
Plan requirement: exporting needs a plan with data exports (Pro and above). Other plans receive 403 Forbidden.
Cells beginning with =, +, - or @ are prefixed with a single quote so spreadsheet apps show them as text instead of evaluating them as formulas. This matters here because visitor names and pages are typed by the public.

List visitors

Overview numbers

Export to CSV

On this page