API Reference

POST /api/collect

Send a pageview or event.

This is the endpoint the tracker posts to. You can post to it from your own server too, with the same fields.

Headers

Content-Type: application/json

Body fields

• s (required) — your site ID
• type — pageview (default) or event
• p — the page path (defaults to /)
• r — the referrer URL, if any
• w — the screen width in pixels
• e — the event name, for an event
• d — the event properties (an object), for an event
• utm_source, utm_medium, utm_campaign — campaign tags; each is trimmed, capped at 100 characters and dropped if it contains @
• data-key — the site's data key, required when the site has one (every site created from the dashboard does)

Example body (pageview)

{
  "s": "abc123",
  "type": "pageview",
  "p": "/pricing",
  "r": "https://chatgpt.com/",
  "w": 1440,
  "utm_campaign": "launch",
  "data-key": "your-site-data-key"
}

Example body (event)

{
  "s": "abc123",
  "type": "event",
  "p": "/pricing",
  "e": "signup",
  "d": {
    "plan": "pro"
  },
  "data-key": "your-site-data-key"
}

Response

HTTP 201 with:

{
  "ok": true
}

Errors

• 400 — the body is not JSON, s is missing, or no site has that ID
• 403 Invalid referer — the request's Referer or Origin host is not the site's domain or one of its aliases (a server-side request without either header passes this check)
• 403 Invalid API key — the site has a data key and the body does not carry it
• 402 — the account's monthly pageview limit is reached

A 202 with {"ok":true} means the request was acknowledged but not recorded: its User-Agent names a known crawler, monitor or link-preview fetcher, or its referrer is a listed spam domain. A scripting client (curl, python-requests, axios, Go, Java) is recorded when the request carries the site's data key and no Referer or Origin header, as in the example below. Add either header to a scripting client and it is dropped like any other automated visit.

Example (cURL)

curl -X POST https://klar.alphabros.eu/api/collect \
  -H "Content-Type: application/json" \
  -d '{"s":"abc123","type":"pageview","p":"/pricing","r":"https://chatgpt.com/","data-key":"your-site-data-key"}'

The data key is the data-key value of your tracking snippet. It is public (it ships in your page) and only lets you send data. It is not an API v1 key: those start with klr_, read your stats, and must stay secret.

GET /api/v1/sites/:siteId/export

Download raw pageviews or events with a site API key.

Headers

Authorization: Bearer klr_your_api_key

Query parameters

• type — pageviews or events (required)
• period — today, 7d, 30d, 90d, year, or all (defaults to 30d)

Returns CSV, capped at 100,000 rows to match the session export. A capped response includes X-Export-Truncated: true. The endpoint uses the same per-key rate limit as the other /api/v1 endpoints.

Example (cURL)

curl -H "Authorization: Bearer klr_your_api_key" \
  "https://klar.alphabros.eu/api/v1/sites/abc123/export?type=pageviews&period=30d"

Authorization: Bearer klr_your_api_key

GET /api/v1/sites/:siteId/channels

Pageviews by channel, and by AI assistant.

The six channels and the rules that assign them are described in AI assistant traffic. aiAssistants breaks the ai_assistant channel down by assistant.

Example (cURL)

curl -H "Authorization: Bearer klr_your_api_key" \
  "https://klar.alphabros.eu/api/v1/sites/abc123/channels?start=2026-10-01T00:00:00Z&end=2026-10-31T23:59:59Z"

Response

{
  "period": {
    "start": "2026-10-01T00:00:00.000Z",
    "end": "2026-10-31T23:59:59.000Z"
  },
  "channels": {
    "direct": 412,
    "search": 380,
    "social": 96,
    "ai_assistant": 57,
    "email": 31,
    "referral": 124
  },
  "aiAssistants": [
    {
      "id": "chatgpt",
      "label": "ChatGPT",
      "pageviews": 33,
      "visitors": 29
    },
    {
      "id": "perplexity",
      "label": "Perplexity",
      "pageviews": 15,
      "visitors": 14
    },
    {
      "id": "claude",
      "label": "Claude",
      "pageviews": 9,
      "visitors": 8
    }
  ],
  "total": 1100
}

• Live data only: imported Plausible or Fathom history is not counted, in the channels or in total.
• The channels are worked out for at most 1,000 distinct referrer and campaign-tag groups per request. On a site with more, the pageviews of the remaining groups count as referral, so the other channels can be slightly low.

GET /api/v1/sites/:siteId/referrers

Top referrers, with the channel summary.

Example (cURL)

curl -H "Authorization: Bearer klr_your_api_key" \
  "https://klar.alphabros.eu/api/v1/sites/abc123/referrers?start=2026-10-01T00:00:00Z&end=2026-10-31T23:59:59Z"

Response

{
  "referrers": [
    {
      "referrer": "(direct)",
      "count": 412,
      "conversions": 0,
      "type": "direct",
      "ctr": "0.00"
    },
    {
      "referrer": "https://www.google.com/",
      "count": 301,
      "conversions": 0,
      "type": "search",
      "ctr": "0.00"
    },
    {
      "referrer": "https://chatgpt.com/",
      "count": 33,
      "conversions": 0,
      "type": "ai_assistant",
      "ctr": "0.00"
    }
  ],
  "total": 1340,
  "summary": {
    "direct": 412,
    "search": 380,
    "social": 96,
    "ai_assistant": 57,
    "email": 31,
    "referral": 124
  }
}

• referrers holds the top 50 referrer URLs of live pageviews. Visits with no referrer are grouped as (direct).
• A row's type comes from its referrer only, so it can be ai_assistant but never email (Email comes from utm_medium).
• summary is the same six-channel object as channels in /channels: live data only, with the same 1,000-group bound.
• total also counts imported pageviews, so on a site with imported history it is larger than the sum of summary. In the example, 240 imported pageviews make the difference.
• conversions is always 0 and ctr always "0.00".