Sessions & journeys

Read a site's visitor sessions and their timelines, explore the paths visitors take (Sankey flow, journey funnel, path exploration), and read cohort retention. A site is addressed by {siteKey} (UUID or domain). All endpoints require Authorization: Bearer {token}.

These are reporting reads: they accept the same date-range inputs (range/from/to) and dashboard dimension filters (country, path, browser, …) documented in Conventions — read that page for the preset range values, the filter key allowlist, the response envelope, and the shared error codes. Only the pieces unique to sessions, journeys, and retention are documented below.

List sessions

GET /api/sites/{siteKey}/sessions

One row per visitor session — the HTTP twin of the web Sessions report. Paginated: keeps the standard data/meta/links envelope at a fixed page size of 25 (?page= only, no ?per_page=).

Path parameters

Query parameters

Each row is aggregated over the resolved range and filters — unlike the session timeline below, whose aggregate covers the whole session regardless of range/filters. A session whose only in-range activity is the automatic engagement beacon is excluded (not a real session).

Response — each item in data:

Status: 200 OK.

curl "https://clickbase.so/api/sites/example.com/sessions?range=last_7_days" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

await fetch('https://clickbase.so/api/sites/example.com/sessions?range=last_7_days', {
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
});

requests.get(
    'https://clickbase.so/api/sites/example.com/sessions',
    params={'range': 'last_7_days'},
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)

Get a session timeline

GET /api/sites/{siteKey}/sessions/{sessionId}

One session's aggregate plus its paged chronological event timeline — the HTTP twin of the web Sessions expand-detail.

By design, the session aggregate here covers the WHOLE session, not just the resolved range/filters (there is no range/filters input on this endpoint) — different from the list row above, which is range/filter-scoped. The two can therefore report different numbers for the same session.

Path parameters

Query parameters

Response

Each entry in events:

Status: 200 OK (a null session still returns 200, not 404, unless the site itself is foreign to the team).

curl "https://clickbase.so/api/sites/example.com/sessions/{sessionId}?limit=50" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

await fetch(`https://clickbase.so/api/sites/example.com/sessions/${sessionId}?limit=50`, {
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
});

requests.get(
    f'https://clickbase.so/api/sites/example.com/sessions/{session_id}',
    params={'limit': 50},
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)

Journey flow (Sankey)

POST /api/sites/{siteKey}/journey/flow

The top most-followed FULL visitor sequences, steps columns deep — feeds the dashboard's Sankey diagram. POST because the request carries a stepFilters payload, not because it writes anything.

IMPORTANT — filter transport. Dashboard dimension filters (country, path, …) ride the query string here, exactly like every other reporting read — never the request body. Sending a query, filters, or filter key in the JSON body is rejected with 422 Unprocessable Entity (a validation error naming that field) rather than being silently ignored, so a client mistake fails loudly instead of quietly returning unfiltered data.

Path parameters

Body parameters

Response

{
    "journeys": [
        {
            "path": [
                { "type": "pageview", "value": "/" },
                { "type": "pageview", "value": "/pricing" }
            ],
            "visitors": 42,
            "percentage": 12.5
        }
    ]
}

Status: 200 OK (422 when a body filter key is sent, or steps/limit are out of bounds).

curl -X POST https://clickbase.so/api/sites/example.com/journey/flow \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"steps": 3, "range": "last_7_days"}'

await fetch('https://clickbase.so/api/sites/example.com/journey/flow', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({ steps: 3, range: 'last_7_days' }),
});

requests.post(
    'https://clickbase.so/api/sites/example.com/journey/flow',
    json={'steps': 3, 'range': 'last_7_days'},
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)

Journey funnel

POST /api/sites/{siteKey}/stats/journey/funnel

Cumulative per-step visitor counts across an ad hoc sequence of steps — the same funnel chart component the saved Funnels report uses, run over free-form steps instead of a saved funnel's goal list. Same query-string-only filter rule as Journey flow above: a query/filters/filter body key is rejected with 422.

Body parameters

Response

{
    "steps": [
        {
            "label": "/",
            "visitors": 100,
            "dropoff": 0,
            "dropoff_percentage": 0.0,
            "conversion_rate": 100.0,
            "conversion_rate_step": 100.0
        },
        {
            "label": "/pricing",
            "visitors": 40,
            "dropoff": 60,
            "dropoff_percentage": 60.0,
            "conversion_rate": 40.0,
            "conversion_rate_step": 40.0
        }
    ]
}

Status: 200 OK (422 when fewer than 2 steps, an unrecognized direction, or a body filter key).

curl -X POST https://clickbase.so/api/sites/example.com/stats/journey/funnel \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"direction": "forward", "steps": [{"type": "pageview", "value": "/"}, {"type": "pageview", "value": "/pricing"}]}'

await fetch('https://clickbase.so/api/sites/example.com/stats/journey/funnel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    direction: 'forward',
    steps: [
      { type: 'pageview', value: '/' },
      { type: 'pageview', value: '/pricing' },
    ],
  }),
});

requests.post(
    'https://clickbase.so/api/sites/example.com/stats/journey/funnel',
    json={
        'direction': 'forward',
        'steps': [
            {'type': 'pageview', 'value': '/'},
            {'type': 'pageview', 'value': '/pricing'},
        ],
    },
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)

Journey path exploration

POST /api/sites/{siteKey}/stats/journey/next-steps

GA4-style "Path Exploration": the events that came immediately after (forward) or before (backward) a given step prefix, ranked by visitor count. Omit steps (or send an empty array) for the entry column — each visitor's first (forward) or last (backward) event in the range. Same query-string-only filter rule as the endpoints above: a query/filters/filter body key is rejected with 422.

Body parameters

Response — a flat JSON array (not wrapped in an object) of:

Status: 200 OK (422 on an unrecognized direction or a body filter key).

curl -X POST https://clickbase.so/api/sites/example.com/stats/journey/next-steps \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"direction": "forward", "steps": [{"type": "pageview", "value": "/"}]}'

await fetch('https://clickbase.so/api/sites/example.com/stats/journey/next-steps', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({ direction: 'forward', steps: [{ type: 'pageview', value: '/' }] }),
});

requests.post(
    'https://clickbase.so/api/sites/example.com/stats/journey/next-steps',
    json={'direction': 'forward', 'steps': [{'type': 'pageview', 'value': '/'}]},
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)

Retention cohorts

GET /api/sites/{siteKey}/retention

Cohort retention: visitors are grouped by the period (day or week) of their first-ever event, then each cohort's activity is tracked forward, period by period. Retention has no dimension filters — only the date range and mode.

Path parameters

Query parameters

Response

{
    "cohorts": {
        "2026-06-29": {
            "size": 120,
            "percentages": [100.0, 42.5, 30.0, null]
        }
    },
    "maxPeriods": 3,
    "mode": "week"
}

Status: 200 OK.

curl "https://clickbase.so/api/sites/example.com/retention?mode=day&range=last_30_days" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

await fetch('https://clickbase.so/api/sites/example.com/retention?mode=day&range=last_30_days', {
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
});

requests.get(
    'https://clickbase.so/api/sites/example.com/retention',
    params={'mode': 'day', 'range': 'last_30_days'},
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)