---
url: 'https://docs.kitbase.dev/index.md'
description: >-
  Developer platform for product analytics, event tracking, bot & crawler
  detection, and AI visibility. SDKs for TypeScript, React, and Angular.
---

# Kitbase

Kitbase is a developer platform for product analytics and feature management: web analytics, custom events, bot & crawler detection, and AI visibility — with SDKs for TypeScript, React, and Angular.

## Set up tracking

Install once, and pageviews, sessions, clicks, and users are tracked automatically. Pick your stack:

New to Kitbase? Start with the [Web Analytics overview](/web-analytics) or the [Quick Start](/getting-started).

## Go deeper

## Watch the bots

Two different features — one keeps bots **out** of your analytics, the other makes them **visible**:

Bot *filtering* — excluding bots from your human visitor counts — is built into the SDK and needs no setup. See [bot filtering vs. bot detection](/crawler-detection#detection-vs-filtering).

## Use the dashboard

## Tools & reference

## Open source

All Kitbase SDKs are MIT-licensed — [source on GitHub](https://github.com/scr2em/kitbase-sdk).

---

---
url: 'https://docs.kitbase.dev/getting-started.md'
description: Install the Kitbase SDK and send your first event in under five minutes.
---

# Getting Started

Get up and running with Kitbase in minutes.

## Installation

::: code-group

```bash [pnpm]
pnpm add @kitbase/analytics
```

```bash [npm]
npm install @kitbase/analytics
```

```bash [yarn]
yarn add @kitbase/analytics
```

:::

## Analytics & Events

Track pageviews, sessions, and custom events.

```typescript
import { init } from '@kitbase/analytics';

const kitbase = init({
  sdkKey: '<YOUR_API_KEY>',
});

// Track custom events
await kitbase.track({
  channel: 'payments',
  event: 'New Subscription',
  user_id: 'user-123',
  icon: '💰',
  notify: true,
  tags: {
    plan: 'premium',
    amount: 9.99,
  },
});
```

[Learn more about Events →](/track-events)

## Next steps

* [Web Analytics overview](/web-analytics) — how capture, filtering, and enrichment fit together.
* [Track Events](/track-events) — channels, tags, notifications, and revenue tracking.
* [SDKs & Tools](/sdks/) — React, Angular, the CLI, and the MCP server.
* [Dashboard guide](/guide/) — analytics, events, sessions, and users views.

---

---
url: 'https://docs.kitbase.dev/web-analytics.md'
description: >-
  Privacy-friendly web analytics with one script tag or an npm SDK. Autocaptured
  pageviews, sessions, clicks, and users — enriched server-side, no cookies.
---

# Web Analytics

Kitbase tracks pageviews, sessions, clicks, scroll depth, outbound links, and users automatically — no cookies, no banners required. Install it once and the [autocapture system](/autocapture) does the rest; add [custom events](/track-events) and [user identification](/identify-users) when you're ready.

Pick your installation path:

::: tip Script or SDK?
Both run the same engine. The [tracking script](/tracking-script) is the npm SDK, pre-bundled and served from `https://kitbase.dev/lite.js` — use it when you don't have (or don't want) a build step. Use the [npm SDK](/sdks/javascript) when you want typed APIs, tree-shaking, and framework integration.
:::

## How it works

1. **Capture** — the script or SDK autocaptures pageviews, sessions, clicks, scroll depth, and outbound links in the browser. See the [autocapture reference](/autocapture) for every event and its payload.
2. **Filter** — obvious non-human traffic (headless browsers, testing tools, HTTP clients, known crawlers) is discarded before it's ever sent, and the server-side attribution pipeline excludes anything flagged as a bot from human counts. No configuration needed.
3. **Enrich** — the backend parses the User-Agent (device, browser, OS), derives geolocation from the IP (then drops the IP unless IP logging is enabled), and extracts UTM parameters. All enriched fields are first-class filter dimensions.
4. **Explore** — metrics, breakdowns, and filters live in the [Analytics dashboard](/guide/analytics); raw events in the [Events view](/guide/events).

## Reporting timezone

Every date boundary in your reports — where "today" starts, which day a visit at 00:30 belongs to, which hour a heatmap cell covers — is resolved in the project's **reporting timezone**. Set it per project under **Settings → General → Reporting**; it defaults to UTC.

It is deliberately a project setting rather than something each request decides. Because the server holds it, the dashboard, the API, the CLI, exports, and the Slack assistant all cut the same period the same way — so two people in different countries reading the same project see the same numbers, and a scheduled export matches the dashboard it came from.

Two things worth knowing before you change it:

* **Past numbers are restated, not lost.** Traffic is stored as exact instants; the timezone only decides where the day boundaries fall. Moving from UTC to `Africa/Cairo` re-cuts yesterday at a different moment, so a daily figure can move. Moving it back restores the previous figures exactly.
* **Explicit dates follow it too.** `from=2026-08-01&to=2026-08-01` means that calendar day in the project's zone, not in the caller's.

Set it from the CLI with:

```bash
kitbase settings update --reportingTimezone Africa/Cairo
```

## Compare to an earlier period {#compare-periods}

Every analytics report that takes a date range answers for two periods in one call: the one you asked for, and an earlier one to measure it against.

**You get a comparison whether or not you ask for one.** Send none of the parameters below and a report compares against the **previous period** — the window of the same length immediately before your selection. Send one to compare against something else.

| Parameter | Value | Notes |
|---|---|---|
| `comparePreset` | `previous_period` · `previous_week` · `previous_month` · `previous_quarter` · `previous_year` | Defaults to `previous_period`. Wins over `compareFrom`/`compareTo` when both are sent |
| `compareFrom` | `YYYY-MM-DD` | Start of a custom window, inclusive. Must be sent with `compareTo` |
| `compareTo` | `YYYY-MM-DD` | End of a custom window, inclusive. Must be sent with `compareFrom` |

Both windows are resolved in the project's **reporting timezone** (above), so a comparison is always cut the same way the period it compares against is. A custom pair may cover a different length than your selection; the presets are described next.

### What each preset means

**`previous_period`** keeps the *length* of your selection and ends exactly where it starts, so the two windows never overlap — 7 days compares against the 7 days immediately before them.

**The calendar presets** answer a different question: how does this compare with how things have been going. Each one is the week, month, quarter or year **running up to** your selection, ending the day it begins — `previous_month` on 5–12 August is 5 July to 5 August. Month lengths clamp, so a selection starting May 31 reaches back to April 30.

Those windows are usually **longer** than your selection, and the figures are reported as they are — a month's traffic really is more than a week's. The delta answers "this week against the month behind it", not "this week against a like-sized week"; use `previous_period` when you want equal lengths.

:::  tip These windows never overlap your selection
Every preset ends where your selection starts, so no row is ever counted on both sides of a comparison — whatever length each side happens to be.
:::

A comparison window may not start **more than a year** before your selection. A comparison you asked for that reaches further is refused with `VAL_001`, as are a lone `compareFrom` or `compareTo` and a pair given back to front — half-honouring any of them would answer a question you did not ask.

The default is treated differently on purpose: select more than a year of traffic and you get the report with **no comparison beside it**, rather than an error. You asked for a report; the comparison was ours to add, so it is ours to drop.

### What comes back

Comparison figures are added to the shape a report already had, and only when you asked for them:

| Field | Where | Meaning |
|---|---|---|
| `comparisonWindow` | Top level of the response | `{ from, to }` in UTC, echoing what was actually read. **`from` is inclusive, `to` is exclusive** |
| `previous…` | On each row | The same figure over the comparison window — `previousCount`, `previousRequestCount`, `previousAvgDurationMs`, and so on, named after the metric it mirrors |
| `absoluteChange` | On each row | Current minus previous, for the metric the report is ranked on. On rows ranked by a **rate** it is a **percentage-point** difference: 0.4286 against 0.2857 reads as `14.3` |
| `percentageChange` | On each row | Relative change. **Null when the previous figure is 0** — no percentage describes going from nothing to something |

Two conventions are worth reading before you chart any of it:

* **Zero and null mean different things.** A count reads `0` when the thing existed but wasn't seen in the comparison window — a crawler that arrived this week reads `previousRequestCount: 0`. An average, a position, or a share reads `null` when it was never measured at all: a page nobody opened has no average duration, and 0 ms would claim it was read instantly.
* **Ranking is always the selected period's.** Which rows appear, and in which order, is decided by the window you selected alone. A page, bot, domain or brand that showed up *only* in the comparison window is not listed, and each listed row's earlier figures are looked up by its own name or URL — never read off whatever occupied that position back then.

Reports that are a **series** rather than a list return the earlier window as its own set of points, carrying that window's own dates. Chart them against each other by position, not by date — the two windows rarely hold the same number of buckets.

### Which reports accept it

| Report | Parameter effect |
|---|---|
| `GET /web-analytics` | Each metric's existing `previous` and `change` read from your chosen window instead of the implicit one |
| `GET /web-analytics/timeline` | The existing `previousPeriod` series reads from your chosen window, bucketed at the same interval |
| `GET /web-analytics/breakdown` | Adds `previousCount` (plus `previousVisitors` / `previousViews` on the `top_page` dimension) and the change fields per row |
| `GET /web-analytics/pages/duration` | Adds `previousAvgDurationMs` and the change fields per page |
| `GET /web-analytics/dimension/timeline` | Adds `comparisonData`, the same daily series over the comparison window |

The summary and the timeline have always reported *some* previous period — the implicit one immediately before your selection. These parameters decide which window that is; they don't add the field.

The same three parameters work on the [crawler reports](/crawler-detection#compare-periods) and on [AI visibility](/ai-visibility#comparison), and on the matching [MCP tools](/sdks/mcp#period-comparison), so a comparison chosen in one place means the same thing everywhere.

## Going deeper

::: info Bots are filtered here — detected elsewhere
Web analytics silently **excludes** bots so your numbers reflect humans. If you want to **see** the bots — which AI crawlers and search engines visit your site, verified against spoofing — that's the separate [Bot & Crawler Detection](/crawler-detection) feature. The difference is explained in [detection vs. filtering](/crawler-detection#detection-vs-filtering).
:::

## Next steps

* [Quick Start](/getting-started) — install the SDK and send your first event.
* [Analytics dashboard guide](/guide/analytics) — metrics, breakdowns, and filtering.
* [API reference](/api-reference) — query events and analytics over REST.

---

---
url: 'https://docs.kitbase.dev/tracking-script.md'
description: >-
  Add Kitbase analytics to any website with a lightweight tracking script.
  Privacy-friendly, no cookies, works on static sites, SPAs, and SSR.
---

# Tracking Script

Kitbase provides a lightweight tracking script for web analytics and event tracking. It is privacy-friendly, requires no cookies by default, and works on any website -- static HTML, single-page applications (SPAs), and server-side rendered (SSR) frameworks alike.

## Installation

### Script Tag (Simplest)

Add these two snippets to your HTML `<head>` section:

```html
<script>
  window.KITBASE_CONFIG = { sdkKey: 'YOUR_SDK_KEY' };
</script>
<script defer src="https://kitbase.dev/lite.js"></script>
```

The `KITBASE_CONFIG` object **must** be set before the tracking script loads. The `defer` attribute ensures the script is fetched in parallel and executed after the HTML is parsed, so it never blocks page rendering.

### NPM Package

For JavaScript/TypeScript projects with a build step, install the SDK as a dependency:

::: code-group

```bash [pnpm]
pnpm add @kitbase/analytics
```

```bash [npm]
npm install @kitbase/analytics
```

```bash [yarn]
yarn add @kitbase/analytics
```

:::

Then initialize the SDK in your application entry point:

```typescript
import { init } from '@kitbase/analytics';

const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  analytics: {
    autoTrackPageViews: true,
    trackBfcacheRestore: true,
    autoTrackOutboundLinks: true,
    autoTrackClicks: true,
    autoTrackScrollDepth: true,
    autoTrackVisibility: true,
  },
});
```

::: tip Lite Build
For a smaller bundle size (~12KB vs ~50KB), use the lite build which excludes offline queue support:

```typescript
import { init } from '@kitbase/analytics/lite';
```

The lite build has the same API surface for analytics and event tracking. Only the offline queue module (`offline` config) is removed.
:::

## Configuration Reference

Below is the full configuration object with every available option and its default value.

```typescript
const kitbase = init({
  // ── Core ───────────────────────────────────────────────
  sdkKey: 'YOUR_SDK_KEY',               // Required. SDK API key from the dashboard.
  debug: false,                         // Enable console logging for troubleshooting.
  baseUrl: 'https://ingest.kitbase.dev', // Ingestion endpoint. Override for self-hosted.
  storage: localStorage,                // Storage backend for the anonymous ID.
                                        // Set to `null` to disable persistence.
  storageKey: 'kitbase_anonymous_id',   // Key used in the storage backend.

  // ── Analytics ──────────────────────────────────────────
  analytics: {
    autoTrackPageViews: true,           // Fire `screen_view` on every navigation.
    trackBfcacheRestore: true,          // Fire `screen_view` on bfcache restore (back/forward in MPAs).
    autoTrackOutboundLinks: true,       // Fire `outbound_link` for external link clicks.
    autoTrackClicks: true,              // Fire `click` for interactive element clicks.
    autoTrackScrollDepth: true,         // Fire `scroll_depth` when the user leaves a page.
    autoTrackVisibility: true,          // Observe `data-kb-track-visibility` elements.
  },

  // ── Offline Queue ──────────────────────────────────────
  offline: {
    enabled: false,                     // Queue events when offline, sync when back.
    maxQueueSize: 1000,                 // Maximum events held in the queue.
    flushInterval: 30000,               // Flush interval in milliseconds (30 s).
    flushBatchSize: 50,                 // Events sent per batch.
    maxRetries: 3,                      // Retry attempts before an event is dropped.
    retryBaseDelay: 1000,               // Base delay for exponential backoff (1 s).
  },
});
```

### Configuration Options Summary

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `sdkKey` | `string` | -- | **Required.** SDK API key from your dashboard. |
| `debug` | `boolean` | `false` | Enable verbose console logging. |
| `baseUrl` | `string` | `'https://ingest.kitbase.dev'` | Ingestion endpoint. Override for self-hosted deployments. |
| `storage` | `Storage \| null` | `localStorage` | Storage backend for anonymous ID persistence. Set to `null` to disable. |
| `storageKey` | `string` | `'kitbase_anonymous_id'` | Key name used in the storage backend. |

#### `analytics`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `autoTrackPageViews` | `boolean` | `true` | Automatically track page views on navigation. |
| `trackBfcacheRestore` | `boolean` | `true` | Track a pageview when the browser restores a page from the back-forward cache (bfcache). Important for MPA sites where back/forward navigation does not re-execute scripts. |
| `autoTrackOutboundLinks` | `boolean` | `true` | Track clicks on links to external domains. |
| `autoTrackClicks` | `boolean` | `true` | Track clicks on interactive elements. |
| `autoTrackScrollDepth` | `boolean` | `true` | Report maximum scroll depth when the user leaves. |
| `autoTrackVisibility` | `boolean` | `true` | Observe elements with `data-kb-track-visibility`. |

#### `offline`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | `boolean` | `false` | Enable the offline event queue. |
| `maxQueueSize` | `number` | `1000` | Maximum events to hold in the queue. |
| `flushInterval` | `number` | `30000` | Interval between automatic flushes (ms). |
| `flushBatchSize` | `number` | `50` | Events sent per flush batch. |
| `maxRetries` | `number` | `3` | Retry attempts before an event is dropped. |
| `retryBaseDelay` | `number` | `1000` | Base delay for exponential backoff (ms). |

## What the Script Does (Behind the Scenes)

When the tracking script loads, it performs the following sequence of actions automatically. Understanding this lifecycle helps you debug issues and reason about the data you see in the dashboard.

### 1. Generates an Anonymous ID

A UUID v4 is generated and stored in `localStorage` under the key `kitbase_anonymous_id`. This ID persists across page loads so the same browser is recognized as the same visitor without cookies. If `storage` is set to `null`, the ID is regenerated on every page load.

### 2. Starts a Session

A `session_start` event is fired with a new session ID (UUID v4). The session remains active as long as events arrive within 30 minutes of inactivity. After 30 minutes of inactivity, the next interaction starts a fresh session.

### 3. Listens for Page Navigations

The SDK patches `history.pushState` and listens for the `popstate` event. This means route changes in single-page applications are detected automatically -- no framework-specific code is needed.

### 4. Tracks Page Views

A `screen_view` event is fired on the initial page load and on every subsequent navigation (pushState or popstate). Each event includes the page path, document title, referrer, and any UTM parameters present in the URL.

### 5. Monitors Clicks on Interactive Elements

A global click listener watches for clicks on interactive elements: `<a>`, `<button>`, `<input>`, `<select>`, `<textarea>`, elements with ARIA roles (`button`, `link`, `menuitem`, `tab`), and custom elements (any tag name containing a hyphen). The SDK uses `composedPath()` to traverse Shadow DOM boundaries, so web components are fully supported.

### 6. Tracks Outbound Links

When a user clicks (or keyboard-activates with Enter/Space) a link pointing to an external domain, an `outbound_link` event is fired with the full URL and the link text. Outbound link clicks are not double-counted by the generic click tracker.

### 7. Measures Scroll Depth

The SDK tracks the maximum scroll depth reached on each page. A `scroll_depth` event with a percentage (0--100) is flushed when the user navigates away (`beforeunload`, `pushState`, `popstate`). Scroll tracking uses `requestAnimationFrame` throttling to avoid scroll jank.

### 8. Observes Element Visibility

Elements annotated with `data-kb-track-visibility` are observed using `IntersectionObserver`. When such an element leaves the viewport (or is removed from the DOM, or the user navigates away), an event is fired reporting how long the element was visible. A `MutationObserver` picks up dynamically added and removed elements.

### 9. Filters Bots Automatically

Before sending any events, the SDK checks for signals that indicate non-human traffic. Events are silently discarded when the page is loaded by:

* **Headless browsers** -- Puppeteer, Playwright, PhantomJS
* **Testing tools** -- Selenium, WebDriver
* **HTTP clients** -- curl, wget, Postman
* **Search engine crawlers** -- Googlebot, Bingbot, Yandex, Baidu
* **Social media crawlers** -- Facebook, Twitter/X, Slack, LinkedIn

No configuration is required. Your analytics will only include real user traffic.

Filtering keeps bots **out** of your analytics. To **see** bot and crawler traffic instead, use the separate [Bot & Crawler Detection](/crawler-detection) feature ([detection vs. filtering](/crawler-detection#detection-vs-filtering)).

### 10. Enriches Data Server-Side

The raw events sent by the browser contain minimal data. The Kitbase backend enriches every event with:

| Enrichment | Source | Fields |
|------------|--------|--------|
| User agent parsing | `User-Agent` header | Device type, browser, browser version, OS, OS version, brand, model |
| IP geolocation | Client IP address | Country, region, city |
| UTM parameters | URL query string | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |

These enriched fields are stored as dedicated columns and available as first-class filter dimensions in the dashboard.

## Accessing the SDK After Load (Script Tag)

When using the script tag method, the SDK instance is exposed on `window.kitbase` after the script finishes loading.

### Tracking Custom Events

```javascript
window.kitbase.track({
  channel: 'engagement',
  event: 'Button Clicked',
  tags: { button_id: 'cta-header' },
});
```

### Identifying Users

```javascript
window.kitbase.identify({
  userId: 'user_123',
  traits: {
    email: 'user@example.com',
    name: 'Jane Doe',
    plan: 'premium',
  },
});
```

### Tracking Revenue

```javascript
window.kitbase.trackRevenue({
  amount: 49.99,
  currency: 'USD',
  orderId: 'order-123',
});
```

::: tip Waiting for the Script
Because the tracking script uses `defer`, it is guaranteed to execute after the DOM is parsed. If you need to call SDK methods from an inline script, use `DOMContentLoaded`:

```html
<script>
  document.addEventListener('DOMContentLoaded', function () {
    window.kitbase.track({
      channel: 'engagement',
      event: 'Page Loaded',
    });
  });
</script>
```

:::

## Data Attribute Events

The SDK supports declarative event tracking through HTML data attributes. No JavaScript is required -- annotate elements and the SDK handles the rest.

### Track Clicks

Add `data-kb-track-click` to fire a named event when the element is clicked:

```html
<button data-kb-track-click="CTA Clicked">Sign Up Now</button>

<!-- With a custom channel (default: "engagement") -->
<button
  data-kb-track-click="Add to Cart"
  data-kb-click-channel="ecommerce"
>
  Add to Cart
</button>
```

When an element has `data-kb-track-click`, the generic `click` auto-tracking is skipped for that click to avoid double-counting.

### Track Visibility

Add `data-kb-track-visibility` to measure how long a section is visible:

```html
<section data-kb-track-visibility="Pricing Section Viewed">
  ...
</section>

<!-- With custom channel and threshold -->
<div
  data-kb-track-visibility="Hero Banner Viewed"
  data-kb-visibility-channel="marketing"
  data-kb-visibility-threshold="0.75"
>
  ...
</div>
```

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `data-kb-track-visibility` | Yes | -- | Event name to fire. |
| `data-kb-visibility-channel` | No | `'engagement'` | Channel for the event. |
| `data-kb-visibility-threshold` | No | `0.5` | IntersectionObserver threshold (0--1). |

## Content Security Policy (CSP)

If your site uses a Content Security Policy, add the following directives to allow the tracking script and its API calls:

```
script-src 'self' https://kitbase.dev;
connect-src 'self' https://ingest.kitbase.dev;
```

## Subresource Integrity (SRI)

For additional security, you can verify the script has not been tampered with by using Subresource Integrity:

```html
<script
  src="https://kitbase.dev/lite.js"
  integrity="sha384-..."
  crossorigin="anonymous"
  defer
></script>
```

Contact support for the current SRI hash, or compute it yourself against the hosted script.

## Framework Integration Tips

### React / Next.js

Use the NPM package. Initialize the SDK in your root layout or `App` component so it runs once on mount:

```tsx
// app/layout.tsx (Next.js App Router) or _app.tsx (Pages Router)
import { init } from '@kitbase/analytics';

const kitbase = init({ sdkKey: 'YOUR_SDK_KEY' });
```

### Vue / Nuxt

Use the NPM package. Initialize in a plugin or in `app.vue`:

```typescript
// plugins/kitbase.client.ts (Nuxt 3)
import { init } from '@kitbase/analytics';

export default defineNuxtPlugin(() => {
  const kitbase = init({ sdkKey: 'YOUR_SDK_KEY' });
  return { provide: { kitbase } };
});
```

### Angular

Use the NPM package. Initialize in an Angular service and inject it where needed. See the [Angular SDK documentation](/sdks/angular) for a full guide.

```typescript
// kitbase.service.ts
import { Injectable } from '@angular/core';
import { init } from '@kitbase/analytics';

@Injectable({ providedIn: 'root' })
export class KitbaseService {
  public readonly client = init({ sdkKey: 'YOUR_SDK_KEY' });
}
```

### Static Sites

Use the script tag method in your HTML `<head>`. No build step required:

```html
<!DOCTYPE html>
<html>
<head>
  <script>
    window.KITBASE_CONFIG = { sdkKey: 'YOUR_SDK_KEY' };
  </script>
  <script defer src="https://kitbase.dev/lite.js"></script>
</head>
<body>
  <!-- Your site content -->
</body>
</html>
```

## Next steps

* [Proxy / Custom Domain](/proxy) -- Route requests through your own domain to bypass ad blockers
* [Analytics](/guide/analytics) -- Pageviews, sessions, bounce rate, and revenue tracking
* [Autocapture](/autocapture) -- Full reference of every automatic event and its payload
* [Custom Events](/track-events) -- Track events with channels, tags, and notifications
* [Identify Users](/identify-users) -- Anonymous tracking and identity resolution
* [JavaScript SDK](/sdks/javascript) -- Offline support and advanced features

---

---
url: 'https://docs.kitbase.dev/track-events.md'
description: >-
  Send custom events with channels, tags, and notifications using the Kitbase
  SDK.
---

# Track Custom Events

Kitbase lets you track custom events with rich metadata to understand what your users are doing, monitor business metrics, and trigger real-time notifications. Events are sent asynchronously to the Kitbase API and processed in the background.

All events are sent via `POST /sdk/v1/logs` with API key authentication (`X-API-Key` header) and return `202 Accepted` for async processing.

## Basic Usage

```typescript
import { init } from '@kitbase/analytics';

const kitbase = init({ sdkKey: 'YOUR_SDK_KEY' });

await kitbase.track({
  channel: 'payments',
  event: 'Purchase Completed',
  tags: {
    amount: 99.99,
    currency: 'USD',
    plan: 'premium'
  }
});
```

## Track Options

The `track` method accepts a `TrackOptions` object with the following fields:

```typescript
interface TrackOptions {
  channel: string;              // Required: event category (e.g., 'payments', 'users', 'errors')
  event: string;                // Required: event name (e.g., 'Purchase Completed')
  user_id?: string;             // Optional: explicit user identifier
  icon?: string;                // Optional: emoji icon for dashboard
  notify?: boolean;             // Optional: trigger real-time notification
  description?: string;         // Optional: human-readable event description
  tags?: Record<string, unknown>; // Optional: metadata (string, number, boolean values)
}
```

| Parameter     | Type      | Required | Description                                      |
|---------------|-----------|----------|--------------------------------------------------|
| `channel`     | `string`  | Yes      | Category for the event (e.g., `"payments"`, `"users"`) |
| `event`       | `string`  | Yes      | Name of the event (e.g., `"Purchase Completed"`) |
| `user_id`     | `string`  | No       | Explicit user identifier                         |
| `icon`        | `string`  | No       | Emoji icon displayed in the dashboard            |
| `notify`      | `boolean` | No       | Trigger a real-time notification                 |
| `description` | `string`  | No       | Human-readable event description                 |
| `tags`        | `object`  | No       | Key-value metadata (string, number, boolean)     |

## Response

A successful call returns a `TrackResponse` with the event's unique identifier and timestamp:

```typescript
interface TrackResponse {
  id: string;        // Unique event ID (UUID)
  event: string;     // Event name
  timestamp: string; // ISO 8601 timestamp
}
```

## Channels

Channels organize your events into logical categories. Use consistent channel names across your application to keep your dashboard clean and filterable.

| Channel          | Use Case                                    |
|------------------|---------------------------------------------|
| `payments`       | Purchases, refunds, subscription changes    |
| `users`          | Signups, logins, profile updates            |
| `errors`         | Application errors, failed requests         |
| `notifications`  | Alerts, messages, delivery status           |
| `api`            | API calls, webhooks, integrations           |
| `system`         | Infrastructure events, deployments          |

You are not limited to these defaults. Custom channels are fully supported -- use whatever names make sense for your domain.

::: tip Channel Naming
Use lowercase, plural nouns for channel names (e.g., `payments`, `errors`, `users`). This keeps your events organized and easy to filter in the dashboard.
:::

## Tags

Tags are key-value metadata attached to events. They allow you to store additional context that you can filter and analyze later.

### Supported Types

| Type      | Example   |
|-----------|-----------|
| `string`  | `"premium"` |
| `number`  | `99.99`   |
| `boolean` | `true`    |

### Example

```typescript
tags: {
  plan_name: 'premium',      // string
  amount: 99.99,             // number
  is_upgrade: true,          // boolean
}
```

::: tip Tag Naming
Use `snake_case` for tag names:

* `plan_name`, `user_type`, `error_code`
* Not: `PlanName`, `planName`, `ERROR-CODE`
  :::

## Server-Side Tag Enrichment

The Kitbase backend automatically enriches every event with additional context derived from the request. These enriched fields are prefixed with `__` and stored as dedicated columns, available as first-class filter dimensions in the dashboard.

### Browser and Device

| Tag                  | Description                                  |
|----------------------|----------------------------------------------|
| `__browser`          | Browser name (Chrome, Firefox, Safari)       |
| `__browser_version`  | Browser version                              |
| `__os`               | Operating system (Windows, macOS, iOS)       |
| `__os_version`       | OS version                                   |
| `__device`           | Device type — see the taxonomy below         |
| `__brand`            | Device brand (Apple, Samsung, Google)        |
| `__model`            | Device model (iPhone 15, Pixel 8)            |
| `__device_confidence`| Detection confidence, `0.0`–`1.0` (see bands below) |
| `__signal_source`    | Which request signal produced the device type |
| `__in_app`           | `1` when the request came from an in-app WebView/Electron context |

**Device taxonomy** (`__device`): `desktop`, `mobile`, `tablet`, `smart_tv`, `set_top_box`, `game_console`, `handheld_game_console`, `wearable`, `automotive`, `xr`, `e_reader`, `voice`, `home_appliance`, `bot`, `unknown`. Device type is detected entirely server-side (no client-provided hints are trusted) and an unidentifiable client stays `unknown` — it is never silently coerced to `desktop`.

**Detection precedence & confidence.** Detection runs a bot gate first, then prefers the strongest available signal:

| Signal (`__signal_source`)         | Source                                    | `__device_confidence` |
|------------------------------------|-------------------------------------------|-----------------------|
| `BOT_RULE`                         | known bot ruleset / robot UA              | `0.99`                |
| `FORM_FACTORS`                     | `Sec-CH-UA-Form-Factors` client hint      | `0.95`                |
| `LOW_ENTROPY_HINTS`                | `Sec-CH-UA-Mobile` + platform hints       | `0.85`                |
| `UA_FUSED` / `UA_ONLY`             | User-Agent parse (with / without hints)   | `0.75`                |
| `UA_FUSED` / `UA_ONLY` (Unknown)   | parsed but class unresolved               | `0.60`                |
| `NONE`                             | no usable signal                          | `0.30`                |

To recover accurate detection on Chromium (whose User-Agent is frozen by User-Agent Reduction), the backend advertises UA Client Hints via `Accept-CH`, with the device-critical subset (`Sec-CH-UA-Form-Factors`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Platform`) also sent as `Critical-CH` so even first-hit requests can be classified from hints. Filter low-confidence rows by `__signal_source`/`__device_confidence` in the dashboard.

> **Known limitation:** iPadOS Safari presents a macOS desktop User-Agent and sends no distinguishing hints, so some iPads are counted as `desktop` (a documented undercount). We do not fingerprint to work around this.

### Bot & Crawler Attribution

Every request is classified by a server-side attribution pipeline that not only detects bots but tries to **verify** their claimed identity — because a bot User-Agent is trivially spoofable.

| Tag | Description |
|-----|-------------|
| `__actor_type` | `human`, `verified_bot`, `spoofed_bot`, `suspected_bot`, or `unknown` |
| `__is_bot` | `1` for any kind of bot (the flag used to exclude bots from human/billing counts) |
| `__bot_name` | Attributed bot name (e.g. `GPTBot`, `Googlebot`) |
| `__bot_vendor` | Operating vendor (e.g. `OpenAI`, `Google`) |
| `__actor_category` | `ai_training`, `ai_search`, `ai_user_fetch`, `search_engine`, `social_preview`, `seo`, `monitoring`, `security_scanner`, `archiver`, `feed_fetcher`, `automation` |
| `__actor_verified` | `1` when the bot's identity was cryptographically/network confirmed |
| `__verification_method` | `web_bot_auth`, `cidr`, `reverse_dns`, or `none` |
| `__actor_confidence` | Classification confidence, `0.0`–`1.0` |
| `__is_ai` | `1` when this is an AI crawler/agent |

**Verification hierarchy** (strongest → weakest), short-circuiting on the first decisive result:

1. **Web Bot Auth** — RFC 9421 Ed25519 HTTP Message Signatures, verified against the signer's `/.well-known/http-message-signatures-directory`. Unspoofable.
2. **Exact CIDR membership** — the client IP must fall inside the vendor's published IP ranges (not just the same ASN, which spoofers share).
3. **Forward-confirmed reverse DNS** — for vendors that publish no IP list (Yandex, Baidu, Amazon, Apple).

A recognized bot UA that **fails** verification (e.g. claims `GPTBot` from a non-OpenAI IP) is flagged `spoofed_bot` — the high-value fraud signal. A UA-only match with no verification is `suspected_bot`.

**Drop vs. store** is controlled by your project's **bot detection** setting:

* **Bot detection ON** → bot events are **stored**, flagged with the attribution above (`is_bot`), and **excluded** from human visitor and billing counts.
* **Bot detection OFF** → bot traffic is **dropped** entirely.

> **Capturing non-JS crawlers:** crawlers like GPTBot and Googlebot fetch your pages without running the JavaScript SDK, so they never reach this enrichment path. To detect them, forward your server/edge request signals to Kitbase — see the [Bot & Crawler Detection setup guides](/crawler-detection) for your platform, or the [endpoint reference](/api-reference#server-side-crawler-detection). Both run the same attribution pipeline.

### Geolocation

| Tag          | Description              |
|--------------|--------------------------|
| `__country`  | Country (derived from IP) |
| `__region`   | Region or state          |
| `__city`     | City                     |

### Page and Attribution

| Tag              | Description          |
|------------------|----------------------|
| `__path`         | Page path            |
| `__referrer`     | Referrer URL         |
| `__utm_source`   | UTM source parameter |
| `__utm_medium`   | UTM medium parameter |
| `__utm_campaign` | UTM campaign parameter |
| `__utm_term`     | UTM term parameter   |
| `__utm_content`  | UTM content parameter |

::: tip Query Filters
These enriched fields are available as filter dimensions in the dashboard. Filter events by browser, country, device, UTM parameters, and more directly from the events list.
:::

## Notifications

When `notify: true` is set, the event triggers a real-time notification in the Kitbase dashboard. Combine with `icon` and `description` to make notifications informative at a glance.

```typescript
await kitbase.track({
  channel: 'payments',
  event: 'Large Purchase',
  icon: '💰',
  notify: true,
  description: 'A customer just made a $500+ purchase',
  tags: { amount: 549.99 }
});
```

Good candidates for notifications:

* New signups and subscriptions
* Failed payments and billing issues
* Critical application errors
* Security events (login from new device)
* Large or unusual transactions

## Revenue Tracking

Track revenue with the dedicated `trackRevenue` method. Revenue events are automatically sent to the `__analytics` channel.

```typescript
await kitbase.trackRevenue({
  amount: 99.99,
  currency: 'USD',
  orderId: 'order_123',
  productId: 'prod_premium',
  tags: { plan: 'premium' }
});
```

This provides structured revenue data in the dashboard, separate from general custom events, so you can track MRR, ARPU, and other financial metrics out of the box.

## Timed Events

Measure how long user flows take by starting a timer and letting the SDK automatically attach the duration when the event is tracked.

```typescript
// Start timing
kitbase.timeEvent('Checkout Flow');

// ... user completes checkout ...

// Track with automatic $duration tag (in milliseconds)
await kitbase.track({
  channel: 'conversions',
  event: 'Checkout Flow',
  tags: { items: 3 }
});
// The $duration tag is automatically added to the event
```

### Methods

| Method                       | Description                                  |
|------------------------------|----------------------------------------------|
| `timeEvent(eventName)`       | Start timing an event                        |
| `cancelTimeEvent(eventName)` | Cancel a timed event without tracking        |
| `getTimedEvents()`           | Get list of event names currently being timed |
| `getEventDuration(eventName)`| Get current elapsed duration in milliseconds |

### Example

```typescript
// Check active timers
const activeTimers = kitbase.getTimedEvents();
// => ['Checkout Flow', 'Video Watched']

// Get duration without tracking
const duration = kitbase.getEventDuration('Checkout Flow');
// => 45000 (ms)

// Cancel a timer
kitbase.cancelTimeEvent('Video Watched');
```

## Super Properties

Super properties are automatically included with every event you track. They are useful for attaching persistent context like app version, environment, or user segment.

```typescript
// Register properties (overwrites existing)
kitbase.register({ app_version: '2.1.0', environment: 'production' });

// Register only if not already set
kitbase.registerOnce({ first_visit_source: 'google' });

// Remove a specific super property
kitbase.unregister('first_visit_source');

// Get all registered super properties
kitbase.getSuperProperties();

// Clear all super properties
kitbase.clearSuperProperties();
```

### Methods

| Method                           | Description                              |
|----------------------------------|------------------------------------------|
| `register(properties)`          | Set properties (overwrites existing)     |
| `registerOnce(properties)`      | Set properties only if not already set   |
| `unregister(key)`               | Remove a specific property               |
| `getSuperProperties()`          | Get all registered properties            |
| `clearSuperProperties()`        | Remove all super properties              |

::: warning In-Memory Storage
Super properties are stored in memory and reset on page reload. For persistent properties, store them externally (e.g., `localStorage`) and call `register()` on initialization.
:::

## Data Attribute Events

Track events declaratively from HTML without writing JavaScript. The SDK automatically binds event listeners based on `data-kb-*` attributes.

### Click Tracking

```html
<button
  data-kb-track-click="Add to Cart"
  data-kb-click-channel="ecommerce"
>
  Add to Cart
</button>
```

When the button is clicked, an event named `"Add to Cart"` is tracked on the `"ecommerce"` channel.

### Visibility Tracking

```html
<section
  data-kb-track-visibility="Pricing Section Viewed"
  data-kb-visibility-channel="marketing"
  data-kb-visibility-threshold="0.75"
>
  <!-- content -->
</section>
```

When 75% of the section becomes visible in the viewport, an event named `"Pricing Section Viewed"` is tracked on the `"marketing"` channel.

## Error Handling

The SDK provides typed error classes so you can handle specific failure modes precisely.

```typescript
import {
  AuthenticationError,
  ValidationError,
  TimeoutError,
  ApiError,
  KitbaseError
} from '@kitbase/analytics';

try {
  await kitbase.track({ channel: 'payments', event: 'Purchase' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401: Invalid or missing API key
  } else if (error instanceof ValidationError) {
    // 400/422: Missing or invalid fields - check error.field
  } else if (error instanceof TimeoutError) {
    // Request timed out (default: 30s)
  } else if (error instanceof ApiError) {
    // Other API error - check error.statusCode and error.response
  } else if (error instanceof KitbaseError) {
    // Generic SDK error
  }
}
```

| Error                 | HTTP Status | Description                            |
|-----------------------|-------------|----------------------------------------|
| `AuthenticationError` | 401         | Invalid or missing API key             |
| `ValidationError`     | 400/422     | Missing or invalid required fields     |
| `TimeoutError`        | --          | Request exceeded 30s timeout           |
| `ApiError`            | 4xx/5xx     | API returned an error response         |

For detailed error handling patterns including retry logic and best practices, see [Error Handling](/error-handling).

## REST API

You can send events directly to the Kitbase REST API without the SDK. This is useful for server-side integrations or languages without an official SDK.

### Single Event

```bash
curl -X POST https://ingest.kitbase.dev/sdk/v1/logs \
  -H "X-API-Key: YOUR_SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Purchase Completed",
    "properties": {
      "channel": "payments",
      "tags": { "amount": 99.99 }
    }
  }'
```

**Response** (`202 Accepted`):

```json
{
  "id": "evt_abc123",
  "event": "Purchase Completed",
  "timestamp": "2026-02-13T12:00:00.000Z"
}
```

### Batch Events

Send multiple events in a single request for better performance:

```
POST /sdk/v1/logs/batch
```

**Request body:**

```json
{
  "events": [
    {
      "event": "Page Viewed",
      "properties": { "channel": "analytics", "tags": { "path": "/pricing" } }
    },
    {
      "event": "CTA Clicked",
      "properties": { "channel": "conversions", "tags": { "button": "signup" } }
    }
  ]
}
```

**Response** (`202 Accepted`):

```json
{
  "accepted": 2,
  "total": 2
}
```

The batch endpoint accepts an array of events and returns the count of accepted events vs. total submitted.

## Next steps

* [Autocapture](/autocapture) — every event Kitbase tracks for you automatically.
* [Identify Users](/identify-users) — attach events to real users instead of anonymous IDs.
* [Events dashboard guide](/guide/events) — viewing, filtering, and analyzing events.
* [API reference](/api-reference#events) — track events over REST without an SDK.

---

---
url: 'https://docs.kitbase.dev/autocapture.md'
description: >-
  Complete reference for Kitbase's autocapture system. Learn about every
  auto-tracked event, its payload, configuration options, and data attributes.
---

# Autocapture

Kitbase automatically captures key user interactions without any manual instrumentation. From the moment you install the SDK, you get pageviews, sessions, clicks, scroll depth, outbound links, and more -- all out of the box.

Every auto-tracked event is sent on the `__analytics` channel and can be individually toggled on or off via configuration. No cookies are used; sessions are managed client-side with UUIDs.

## Configuration

### SDK initialization

Pass analytics options when creating the Kitbase instance. All flags default to `true` unless noted.

```typescript
import { init } from '@kitbase/analytics';

const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  analytics: {
    autoTrackPageViews: true,      // screen_view events
    trackBfcacheRestore: true,     // screen_view on bfcache restore (back/forward in MPAs)
    autoTrackOutboundLinks: true,  // outbound_link events
    autoTrackClicks: true,         // click events
    autoTrackScrollDepth: true,    // scroll_depth events
    autoTrackVisibility: true,     // data-kb-track-visibility events
    autoTrackWebVitals: false,     // web_vitals events (opt-in)
    autoDetectFrustration: true,   // rage_click and dead_click events
  }
});
```

### Script tag configuration

If you load Kitbase via a `<script>` tag, set the global config object before the SDK loads:

```html
<script>
  window.KITBASE_CONFIG = {
    sdkKey: 'YOUR_SDK_KEY',
    analytics: {
      autoTrackPageViews: true,
      autoTrackClicks: false,  // disable click tracking
    }
  };
</script>
<script src="https://kitbase.dev/lite.js"></script>
```

Any option you omit defaults to `true`.

## Auto-Tracked Events Reference

The table below is a quick-reference summary. Detailed sections for each event follow.

| Event | Config Flag | Channel | Fires When |
|-------|-------------|---------|------------|
| [`session_start`](#session-start) | -- (always on) | `__analytics` | New session begins |
| [`session_end`](#session-end) | -- (always on) | `__analytics` | Session times out (server-generated) |
| [`screen_view`](#screen-view) | `autoTrackPageViews`, `trackBfcacheRestore` | `__analytics` | Page navigation or bfcache restore |
| [`click`](#click) | `autoTrackClicks` | `__analytics` | User clicks interactive element |
| [`outbound_link`](#outbound-link) | `autoTrackOutboundLinks` | `__analytics` | User clicks external link |
| [`scroll_depth`](#scroll-depth) | `autoTrackScrollDepth` | `__analytics` | User leaves a page |
| [`rage_click`](#rage-click) | `autoDetectFrustration` | `__analytics` | 3+ clicks within 1s in same area |
| [`dead_click`](#dead-click) | `autoDetectFrustration` | `__analytics` | Click with no DOM response within 1s |
| [`web_vitals`](#web-vitals) | `autoTrackWebVitals` | `__analytics` | Once per page load (opt-in) |
| [`revenue`](#revenue) | -- (explicit call) | `__analytics` | `trackRevenue()` is called |

***

### session\_start

Fired when a new session begins. A session starts on the first page load or after 30 minutes of inactivity (configurable).

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `session_start` |
| **Config** | Always enabled |

**Tags:**

Standard enrichment tags only (see [Server-Side Enrichment](#server-side-enrichment) below).

**Session management API:**

| Method | Returns | Description |
|--------|---------|-------------|
| `kitbase.getSession()` | `Session` | Full session object |
| `kitbase.getSessionId()` | `string` | Current session UUID |
| `kitbase.reset()` | `void` | End current session and start a new one |

**Example payload:**

```json
{
  "channel": "__analytics",
  "event": "session_start",
  "client_timestamp": 1707840000000,
  "client_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {}
}
```

***

### session\_end

Fired server-side when a session times out (no new events received within the session timeout window). This event is **not** sent by the SDK -- it is generated by the Kitbase backend.

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `session_end` |
| **Config** | Always enabled |

**Computed fields:**

| Field | Type | Description |
|-------|------|-------------|
| `duration` | `number` | Session duration in milliseconds (last event timestamp minus session start timestamp) |
| `bounce` | `boolean` | `true` if the session had only one page view |
| `path` | `string` | Last viewed page path (exit page) |

The `session_end` event inherits the device, geo, UTM, and referrer data from the session. It is used to compute bounce rate, average session duration, and exit pages in the analytics dashboard.

::: info Server-generated
Unlike other auto-tracked events, `session_end` is created entirely by the backend. The SDK does not send this event. It fires after the session timeout (default 30 minutes) with no further activity.
:::

***

### screen\_view

Fired on every page navigation -- initial load, History API calls (`pushState`, `replaceState`), and `popstate` events. Also fired when the browser restores a page from the back-forward cache (bfcache), which is common on MPA sites where back/forward navigation does not re-execute scripts.

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `screen_view` |
| **Config** | `autoTrackPageViews` (default `true`); bfcache restore controlled by `trackBfcacheRestore` (default `true`) |

**Tags:**

| Tag | Type | Description |
|-----|------|-------------|
| `__path` | `string` | `window.location.pathname` |
| `__title` | `string` | `document.title` |
| `__referrer` | `string` | `document.referrer` |
| `__utm_source` | `string` | UTM source parameter (if present) |
| `__utm_medium` | `string` | UTM medium parameter (if present) |
| `__utm_campaign` | `string` | UTM campaign parameter (if present) |
| `__utm_term` | `string` | UTM term parameter (if present) |
| `__utm_content` | `string` | UTM content parameter (if present) |

**SPA support:**

The SDK automatically patches `history.pushState` and `history.replaceState` so that client-side navigation in React Router, Vue Router, Angular Router, Next.js, Nuxt, and any other History API-based router triggers a `screen_view` without additional configuration.

**bfcache restore (MPA sites):**

On multi-page sites (e.g., Astro without View Transitions), pressing the browser back or forward button may restore the page from the back-forward cache instead of reloading it. Since scripts do not re-execute in this case, pageviews would otherwise be missed. When `trackBfcacheRestore` is enabled (the default), the SDK listens for the `pageshow` event with `event.persisted === true` and sends a `screen_view`. Set `trackBfcacheRestore: false` to disable this behavior.

**Manual page view tracking:**

```typescript
kitbase.trackPageView({
  path: '/custom-path',
  referrer: 'https://example.com',
  title: 'Custom Page Title',
});
```

**Example payload:**

```json
{
  "channel": "__analytics",
  "event": "screen_view",
  "client_timestamp": 1707840012000,
  "client_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "__path": "/pricing",
    "__title": "Pricing - Kitbase",
    "__referrer": "https://google.com",
    "__utm_source": "google",
    "__utm_medium": "cpc"
  }
}
```

***

### click

Fired when a user clicks an interactive element.

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `click` |
| **Config** | `autoTrackClicks` (default `true`) |

**Tags:**

| Tag | Type | Description |
|-----|------|-------------|
| `__tag` | `string` | HTML tag name (e.g. `button`, `a`, `ion-button`) |
| `__id` | `string` | Element `id` attribute |
| `__class` | `string` | Element `className` |
| `__text` | `string` | Text content (trimmed, max 100 characters) |
| `__href` | `string` | `href` attribute (if present) |
| `__path` | `string` | `window.location.pathname` |

**Detected elements:**

The SDK listens for clicks on the following interactive elements:

* `a`, `button`, `input`, `select`, `textarea`
* `[role="button"]`, `[role="link"]`, `[role="menuitem"]`, `[role="tab"]`
* Custom elements (any element whose tag name contains `-`, e.g. `ion-button`, `my-dropdown`)

**Shadow DOM support:**

The SDK uses `composedPath()` to traverse Shadow DOM boundaries. When a matched element lives inside a Shadow DOM, the custom-element host is reported.

::: tip No double-counting
When `autoTrackOutboundLinks` is also enabled, clicks on external links are handled by the `outbound_link` event and skipped by click tracking. Similarly, elements with a `data-kb-track-click` attribute fire only the named event, not the generic `click`.
:::

**Text selection is not a click:**

* Repeated clicks of a multi-click sequence (double-click to select a word, triple-click to select a line) count as a single `click` -- only the first click of the sequence is tracked.
* A click that finishes a text-selection drag inside an `input` or `textarea` (the field has a non-collapsed selection when the click fires) is not tracked at all.

**Example payload:**

```json
{
  "channel": "__analytics",
  "event": "click",
  "client_timestamp": 1707840045000,
  "client_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "__tag": "button",
    "__id": "signup-btn",
    "__class": "btn btn-primary",
    "__text": "Start Free Trial",
    "__path": "/pricing"
  }
}
```

***

### outbound\_link

Fired when a user clicks or keyboard-activates (`Enter`/`Space`) a link pointing to an external domain (different hostname).

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `outbound_link` |
| **Config** | `autoTrackOutboundLinks` (default `true`) |

**Tags:**

| Tag | Type | Description |
|-----|------|-------------|
| `__url` | `string` | Full destination URL |
| `__text` | `string` | Link text content (trimmed) |

**Example payload:**

```json
{
  "channel": "__analytics",
  "event": "outbound_link",
  "client_timestamp": 1707840060000,
  "client_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "__url": "https://github.com/kitbase-dev",
    "__text": "View on GitHub"
  }
}
```

***

### scroll\_depth

Fired when the user navigates away from a page (or closes the tab). Reports the maximum scroll depth reached during the page visit.

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `scroll_depth` |
| **Config** | `autoTrackScrollDepth` (default `true`) |

**Tags:**

| Tag | Type | Description |
|-----|------|-------------|
| `__depth` | `number` | Maximum scroll depth as a percentage (0--100) |
| `__path` | `string` | `window.location.pathname` |

**Trigger:** Flushed on `beforeunload`, `history.pushState`, and `popstate`. Scroll position is sampled using `requestAnimationFrame` throttling to avoid scroll jank.

**Example payload:**

```json
{
  "channel": "__analytics",
  "event": "scroll_depth",
  "client_timestamp": 1707840120000,
  "client_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "__depth": 72,
    "__path": "/blog/getting-started"
  }
}
```

***

### rage\_click

Fired when the SDK detects 3 or more clicks within 1 second in the same area (30px radius) -- a strong signal of user frustration.

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `rage_click` |
| **Config** | `autoDetectFrustration` (default `true`) |

**Tags:**

| Tag | Type | Description |
|-----|------|-------------|
| `__selector` | `string` | CSS selector of the clicked element |
| `__tag` | `string` | HTML tag name (e.g. `button`, `div`) |
| `__id` | `string` | Element `id` attribute |
| `__class` | `string` | Element `className` |
| `__text` | `string` | Text content (trimmed, max 100 characters) |
| `__click_count` | `number` | Number of rapid clicks detected |
| `__path` | `string` | `window.location.pathname` |

**Example payload:**

```json
{
  "channel": "__analytics",
  "event": "rage_click",
  "client_timestamp": 1707840300000,
  "client_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "__selector": "button.submit-btn",
    "__tag": "button",
    "__id": "submit-btn",
    "__class": "submit-btn btn-primary",
    "__text": "Submit",
    "__click_count": 5,
    "__path": "/checkout"
  }
}
```

::: tip Frustration analytics
Rage clicks are surfaced in the **Frustration Signals** dashboard, which shows top pages and elements by frustration score. The frustration score is calculated as `rage_clicks * 3 + dead_clicks`.
:::

***

### dead\_click

Fired when the SDK detects a click on an interactive element that produces no DOM change within 1 second -- suggesting the user expected something to happen but nothing did. Uses a `MutationObserver` to watch for child list, attribute, and character data changes.

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `dead_click` |
| **Config** | `autoDetectFrustration` (default `true`) |

**Tags:**

| Tag | Type | Description |
|-----|------|-------------|
| `__selector` | `string` | CSS selector of the clicked element |
| `__tag` | `string` | HTML tag name (e.g. `button`, `a`) |
| `__id` | `string` | Element `id` attribute |
| `__class` | `string` | Element `className` |
| `__text` | `string` | Text content (trimmed, max 100 characters) |
| `__path` | `string` | `window.location.pathname` |

**Excluded elements:**

Dead click detection is skipped where the expected response to a click doesn't mutate the DOM:

* Links with an `href` -- navigation is the expected outcome.
* `<select>` elements -- native dropdowns render outside the DOM.
* Form fields (`textarea` and all `input` types except `button`, `submit`, `reset`, `image`) -- focus, text selection, toggling checked state, and native picker UIs produce no DOM mutation.
* Multi-click sequences (double/triple-click, e.g. text selection) are ignored entirely.

**Example payload:**

```json
{
  "channel": "__analytics",
  "event": "dead_click",
  "client_timestamp": 1707840310000,
  "client_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "__selector": "div.card-header",
    "__tag": "div",
    "__id": "",
    "__class": "card-header",
    "__text": "Premium Plan",
    "__path": "/pricing"
  }
}
```

::: tip Frustration analytics
Dead clicks are surfaced alongside rage clicks in the **Frustration Signals** dashboard. Use them to identify UI elements that look clickable but aren't, so you can improve your design.
:::

***

### revenue

Fired when `trackRevenue()` is called. Included here for completeness since it uses the internal `__analytics` channel.

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `revenue` |

**Tags:**

| Tag | Type | Description |
|-----|------|-------------|
| `__revenue` | `number` | Revenue amount |
| `__currency` | `string` | Currency code (default `'USD'`) |
| + custom tags | | Any additional tags passed via the `tags` option |

**Usage:**

```typescript
kitbase.trackRevenue({
  amount: 49.99,
  currency: 'USD',
  tags: {
    plan: 'pro',
    interval: 'monthly',
  },
});
```

**Example payload:**

```json
{
  "channel": "__analytics",
  "event": "revenue",
  "client_timestamp": 1707840200000,
  "client_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "__revenue": 49.99,
    "__currency": "USD",
    "plan": "pro",
    "interval": "monthly"
  }
}
```

***

### web\_vitals

Fired once per page load when Core Web Vitals metrics have been collected. This event is **opt-in** and must be explicitly enabled.

| Field | Value |
|-------|-------|
| **Channel** | `__analytics` |
| **Event** | `web_vitals` |
| **Config** | `autoTrackWebVitals` (default `false`) |

**Tags (only collected metrics are included):**

| Tag | Type | Description |
|-----|------|-------------|
| `__lcp` | `number` | Largest Contentful Paint -- loading performance (ms) |
| `__cls` | `number` | Cumulative Layout Shift -- visual stability (score) |
| `__inp` | `number` | Interaction to Next Paint -- interactivity (ms) |
| `__fcp` | `number` | First Contentful Paint -- first render (ms) |
| `__ttfb` | `number` | Time to First Byte -- server response time (ms) |

**Usage:**

```typescript
const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  analytics: {
    autoTrackWebVitals: true,
  }
});
```

A 30-second timeout ensures the event is sent even if some metrics never fire (e.g., INP requires user interaction). Only metrics that were successfully collected are included in the tags.

**Example payload:**

```json
{
  "channel": "__analytics",
  "event": "web_vitals",
  "client_timestamp": 1707840500000,
  "client_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "__lcp": 1250,
    "__cls": 0.05,
    "__inp": 180,
    "__fcp": 800,
    "__ttfb": 120
  }
}
```

***

## Data Attribute Events {#data-attributes}

Data attributes let you fire named events directly from HTML -- no JavaScript required. Annotate any element and the SDK handles the rest. These work with Angular, React, vanilla HTML, or any framework.

::: tip Custom channel
Unlike the automatic events above that always use the `__analytics` channel, data-attribute events use the channel **you** specify (defaulting to `engagement`).
:::

### data-kb-track-click

Track custom named click events without writing JavaScript.

| Field | Value |
|-------|-------|
| **Channel** | User-specified (default `engagement`) |
| **Event** | Value of the `data-kb-track-click` attribute |
| **Config** | `autoTrackClicks` (default `true`) |

**HTML attributes:**

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `data-kb-track-click` | Yes | -- | Event name to fire |
| `data-kb-click-channel` | No | `engagement` | Channel for the event |

**Tags:**

| Tag | Type | Description |
|-----|------|-------------|
| `__path` | `string` | `window.location.pathname` |

**Example:**

```html
<!-- Basic usage -->
<button data-kb-track-click="CTA Clicked">Sign Up Now</button>

<!-- With custom channel -->
<button
  data-kb-track-click="Add to Cart"
  data-kb-click-channel="ecommerce"
>
  Add to Cart
</button>
```

When an element has `data-kb-track-click`, the generic `click` auto-tracking is **skipped** for that element to avoid double-counting. The SDK uses `closest()` to find the nearest annotated ancestor, so child elements inside an annotated parent are also covered.

***

### data-kb-track-visibility

Track how long elements are visible in the viewport. The event fires when the tracked element leaves the viewport, is removed from the DOM, or the user navigates away.

| Field | Value |
|-------|-------|
| **Channel** | User-specified (default `engagement`) |
| **Event** | Value of the `data-kb-track-visibility` attribute |
| **Config** | `autoTrackVisibility` (default `true`) |

**HTML attributes:**

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `data-kb-track-visibility` | Yes | -- | Event name to fire |
| `data-kb-visibility-channel` | No | `engagement` | Channel for the event |
| `data-kb-visibility-threshold` | No | `0.5` | IntersectionObserver threshold (0--1) |

**Tags:**

| Tag | Type | Description |
|-----|------|-------------|
| `duration_seconds` | `number` | Total visible time, rounded to whole seconds |
| `duration_ms` | `number` | Total visible time in milliseconds |

**Example:**

```html
<!-- Track a section with default settings -->
<section data-kb-track-visibility="Pricing Section Viewed">
  ...
</section>

<!-- Custom channel and threshold -->
<section
  data-kb-track-visibility="Hero Banner Viewed"
  data-kb-visibility-channel="marketing"
  data-kb-visibility-threshold="0.75"
>
  ...
</section>
```

The SDK uses `IntersectionObserver` to detect enter/leave viewport transitions and `MutationObserver` to pick up dynamically added or removed elements. Visibility data is flushed on `beforeunload`, `history.pushState`, `popstate`, and element removal.

***

## Common Fields on All Auto-Tracked Events

Every auto-tracked event includes the following fields in its payload:

| Field | Type | Description |
|-------|------|-------------|
| `channel` | `string` | Event channel -- always `__analytics` for auto-tracked events, user-specified for data-attribute events |
| `event` | `string` | Event name (e.g. `screen_view`, `click`) |
| `client_timestamp` | `number` | `Date.now()` when the event was created |
| `client_session_id` | `string` | UUID v4, rotated after the session timeout (default 30 min inactivity) |
| `sdk_version` | `string` | Version of the Kitbase SDK package that produced the event (e.g. `0.1.8`) |
| `tags` | `object` | Merged super properties + event-specific tags |
| `user_id` | `string` | Present only if the user has been identified via `kitbase.identify(...)` |

***

## Server-Side Enrichment

All events -- both auto-tracked and manually tracked -- are enriched server-side before storage. These enrichment tags are available as first-class filter dimensions in the dashboard.

**Browser and OS:**

| Tag | Description |
|-----|-------------|
| `__browser` | Browser name (Chrome, Firefox, Safari, Edge) |
| `__browser_version` | Browser version string |
| `__os` | Operating system (Windows, macOS, iOS, Android, Linux) |
| `__os_version` | OS version string |

**Device:**

| Tag | Description |
|-----|-------------|
| `__device` | Device type (full taxonomy below) |
| `__brand` | Device brand (Apple, Samsung, Google, etc.) |
| `__model` | Device model (iPhone 15, Pixel 8, Galaxy S24, etc.) |
| `__device_confidence` | Detection confidence, `0.0`–`1.0` |
| `__signal_source` | Which request signal produced the device type (`FORM_FACTORS`, `LOW_ENTROPY_HINTS`, `UA_FUSED`, `UA_ONLY`, `BOT_RULE`, `NONE`) |
| `__in_app` | `1` for in-app WebView/Electron contexts |

`__device` values: `desktop`, `mobile`, `tablet`, `smart_tv`, `set_top_box`, `game_console`, `handheld_game_console`, `wearable`, `automotive`, `xr`, `e_reader`, `voice`, `home_appliance`, `bot`, `unknown`. Detection is fully server-side and client-hints-aware (the backend advertises `Accept-CH`/`Critical-CH`); an unidentifiable client stays `unknown` rather than defaulting to `desktop`. See [Server-Side Tag Enrichment](/track-events#server-side-tag-enrichment) for the precedence and confidence bands.

**Bot & crawler attribution:** events are also tagged with `__actor_type` (`human`/`verified_bot`/`spoofed_bot`/`suspected_bot`), `__is_bot`, `__bot_name`, `__bot_vendor`, `__actor_category`, `__actor_verified`, `__verification_method`, `__actor_confidence`, and `__is_ai`. Bots are verified (not just UA-matched) via Web Bot Auth → exact CIDR → forward-confirmed rDNS, so a spoofed bot UA is flagged rather than trusted. With bot detection **on**, bot events are stored (flagged, excluded from human/billing counts); **off**, they are dropped. See [Bot & Crawler Attribution](/track-events#bot-crawler-attribution).

**Geolocation (from IP):**

| Tag | Description |
|-----|-------------|
| `__country` | Country name |
| `__region` | Region or state |
| `__city` | City name |

::: info Privacy
IP addresses are used only for geolocation enrichment and are **not** stored. See [Analytics Guide — Privacy](/guide/analytics#privacy) for details.
:::

***

## Bot Filtering

Kitbase automatically filters bot traffic so your analytics stay clean. No configuration is needed.

The following are detected and excluded:

| Category | Examples |
|----------|----------|
| Headless browsers | Puppeteer, Playwright, PhantomJS |
| Testing tools | Selenium, WebDriver, Cypress |
| HTTP clients | curl, wget, Postman, HTTPie |
| Search crawlers | Googlebot, Bingbot, DuckDuckBot, Yandex, Baidu |
| Social crawlers | Twitterbot, Facebookbot, LinkedInBot |
| Monitoring tools | UptimeRobot, Pingdom, New Relic |

Bot detection runs automatically on every incoming event. Detected bot traffic is silently discarded before it reaches your dashboard or analytics queries.

::: info Filtering ≠ detection
This section is about keeping bots **out** of your human analytics. If you want to **see** bot traffic — which AI crawlers and search engines visit your site, verified against spoofing — that's the separate, opt-in [Bot & Crawler Detection](/crawler-detection) feature. See [detection vs. filtering](/crawler-detection#detection-vs-filtering).
:::

***

## Disabling Specific Auto-Track Features

You can selectively disable any auto-track feature while keeping the rest active. Set the corresponding flag to `false` in your configuration.

### Disable a single feature

```typescript
const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  analytics: {
    autoTrackClicks: false, // disable click tracking
    // everything else remains enabled by default
  }
});
```

### Disable multiple features

```typescript
const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  analytics: {
    autoTrackClicks: false,
    autoTrackScrollDepth: false,
    autoTrackOutboundLinks: false,
    // only pageviews and visibility remain active
  }
});
```

### Disable all auto-tracking

If you want full manual control, disable every flag:

```typescript
const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  analytics: {
    autoTrackPageViews: false,
    trackBfcacheRestore: false,
    autoTrackOutboundLinks: false,
    autoTrackClicks: false,
    autoTrackScrollDepth: false,
    autoTrackVisibility: false,
    autoTrackWebVitals: false,
    autoDetectFrustration: false,
  }
});
```

You can still track events manually using `kitbase.track(...)`, `kitbase.trackPageView(...)`, and `kitbase.trackRevenue(...)`.

### Script tag configuration

```html
<script>
  window.KITBASE_CONFIG = {
    sdkKey: 'YOUR_SDK_KEY',
    analytics: {
      autoTrackPageViews: true,
      autoTrackOutboundLinks: false,  // disabled
      autoTrackClicks: false,         // disabled
      autoTrackScrollDepth: true,
      autoTrackVisibility: true,
    }
  };
</script>
```

### Configuration reference

| Flag | Event(s) Controlled | Default |
|------|---------------------|---------|
| `autoTrackPageViews` | `screen_view` | `true` |
| `trackBfcacheRestore` | `screen_view` (bfcache restore) | `true` |
| `autoTrackOutboundLinks` | `outbound_link` | `true` |
| `autoTrackClicks` | `click`, `data-kb-track-click` | `true` |
| `autoTrackScrollDepth` | `scroll_depth` | `true` |
| `autoTrackVisibility` | `data-kb-track-visibility` | `true` |
| `autoTrackWebVitals` | `web_vitals` | `false` |
| `autoDetectFrustration` | `rage_click`, `dead_click` | `true` |

## Next steps

* [Track Events](/track-events) — add custom events alongside the automatic ones.
* [Web Analytics overview](/web-analytics) — how capture, filtering, and enrichment fit together.
* [Analytics dashboard guide](/guide/analytics) — where all these events surface.
* [Bot & Crawler Detection](/crawler-detection) — see the bots that filtering keeps out of these numbers.

---

---
url: 'https://docs.kitbase.dev/identify-users.md'
description: >-
  Learn how to identify users in Kitbase, link anonymous activity to real users,
  and manage identity across devices.
---

# Identify Users

Link anonymous visitors to known users so every event, from first page view to final purchase, is attributed to a single person.

## Overview

Kitbase tracks users with two identifiers:

| Identifier | Description |
|------------|-------------|
| `anonymous_id` | Auto-generated UUID assigned to every visitor before they log in |
| `user_id` | Your unique user identifier, set when you call `identify()` |

Before identification, all events are linked to the auto-generated anonymous ID. After `identify()` is called, the SDK sends a request to `POST /sdk/v1/identify` (authenticated with your SDK key), and subsequent events are attributed to the real user. The server also backfills past anonymous events so nothing is lost.

## How It Works

```
1. User visits site     → anonymous_id generated (UUID, stored in localStorage)
2. User browses         → events tracked with anonymous_id only
3. User logs in         → identify(userId, traits) called
4. SDK sends request    → server links anonymous_id to user_id
5. Server backfills     → previous anonymous events now attributed to user
6. Subsequent events    → include both anonymous_id and user_id
```

## Basic Usage

Call `identify()` immediately after the user authenticates:

```typescript
// After user logs in
await kitbase.identify({
  userId: 'user_123',
  traits: {
    email: 'jane@example.com',
    name: 'Jane Doe',
    plan: 'premium',
    company: 'Acme Inc'
  }
});
```

::: warning Identity Linking Requires identify()
Kitbase does **not** automatically link anonymous users to identified users. You must explicitly call `identify()` after authentication.
:::

## Identify Options

```typescript
interface IdentifyOptions {
  userId: string;                       // Required: your unique user identifier
  traits?: Record<string, unknown>;     // Optional: user properties
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userId` | `string` | Yes | Your unique user identifier (database ID recommended) |
| `traits` | `Record<string, unknown>` | No | Arbitrary key-value pairs describing the user |

Traits can include any key-value pairs. Common examples:

| Trait | Example |
|-------|---------|
| `email` | `"jane@example.com"` |
| `name` | `"Jane Doe"` |
| `plan` | `"premium"` |
| `company` | `"Acme Inc"` |
| `role` | `"admin"` |
| `created_at` | `"2025-03-15T10:00:00Z"` |

## When to Call identify()

Call `identify()` immediately after any of these events:

* **After login** (email/password, OAuth, magic link)
* **After signup** (new account creation)
* **After OAuth callback** (Google, GitHub, etc.)
* **On app load** when the user is already authenticated (check your auth state)

```typescript
// After OAuth login
async function handleOAuthCallback(user) {
  await kitbase.identify({
    userId: user.id,
    traits: {
      email: user.email,
      name: user.name,
      provider: 'google'
    }
  });
}

// On app load if already authenticated
if (currentUser) {
  await kitbase.identify({
    userId: currentUser.id,
    traits: {
      email: currentUser.email,
      plan: currentUser.plan
    }
  });
}
```

::: tip Call identify() as early as possible
The sooner you identify a user after authentication, the fewer events remain anonymous. Place your `identify()` call at the earliest point in your auth flow.
:::

## Anonymous ID Management

Retrieve the current identifiers at any time:

```typescript
kitbase.getAnonymousId();  // Returns current anonymous UUID
kitbase.getUserId();       // Returns user_id if identified, null otherwise
```

### Storage Options

The anonymous ID is persisted across page reloads. You can configure how and where it is stored:

```typescript
// Default: localStorage
const kitbase = init({
  sdkKey: '<YOUR_SDK_KEY>',
  storage: localStorage
});

// Custom storage (must implement getItem / setItem / removeItem)
const kitbase = init({
  sdkKey: '<YOUR_SDK_KEY>',
  storage: myCustomStorage
});

// No persistence (new anonymous ID generated each session)
const kitbase = init({
  sdkKey: '<YOUR_SDK_KEY>',
  storage: null
});
```

## Reset Identity

Clear the current user and start a fresh anonymous session:

```typescript
kitbase.reset();
// Clears user_id, generates a new anonymous_id, starts a new session
```

Use `reset()` when:

* The user **logs out**
* The user **switches accounts**

```typescript
async function handleLogout() {
  await authService.logout();
  kitbase.reset(); // Start tracking as a new anonymous user
}
```

## Multi-Device Support

When the same person uses your app on multiple devices:

* Each device generates its own `anonymous_id`
* Calling `identify()` with the same `userId` on each device links all activity to one user
* Events from every device are attributed to the same user profile

```typescript
// Device A: anonymous_id = "aaa-111"
await kitbase.identify({ userId: 'user_123' });
// -> aaa-111 linked to user_123

// Device B: anonymous_id = "bbb-222"
await kitbase.identify({ userId: 'user_123' });
// -> bbb-222 also linked to user_123

// All events from both devices are now attributed to user_123
```

::: tip MAU Accuracy
Identity resolution prevents double-counting users who browse anonymously before signing in. A user who visits your site anonymously and later creates an account counts as one MAU, not two.
:::

## Server-Side Behavior

When `identify()` is called, the following happens on the server:

1. The SDK sends `POST /sdk/v1/identify` with `{ userId, anonymousId, traits }`
2. The server creates a link between the `anonymous_id` and the `user_id`
3. The server backfills `user_id` on all past events matching that `anonymous_id` in ClickHouse
4. The server responds with:

```json
{
  "success": true,
  "userId": "user_123",
  "previouslyLinked": false
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | `boolean` | Whether the identification succeeded |
| `userId` | `string` | The identified user ID |
| `previouslyLinked` | `boolean` | `true` if this anonymous ID was already linked to this user |

## REST API (Direct)

You can call the identify endpoint directly without the SDK:

```bash
curl -X POST https://ingest.kitbase.dev/sdk/v1/identify \
  -H "x-sdk-key: YOUR_SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "anonymous_id": "550e8400-e29b-41d4-a716-446655440000",
    "traits": {
      "email": "jane@example.com",
      "name": "Jane Doe"
    }
  }'
```

## Best Practices

### Use consistent user IDs

Always use the same identifier format for a given user. Database IDs or UUIDs work well:

```typescript
// Good: consistent database ID
await kitbase.identify({ userId: user.id });

// Bad: mixing formats across your app
await kitbase.identify({ userId: user.email });   // email in one place
await kitbase.identify({ userId: String(user.id) }); // numeric ID elsewhere
```

### Avoid PII as user IDs

Do not use personally identifiable information (email addresses, phone numbers) as the `userId`. Use opaque database IDs instead, and pass PII as traits:

```typescript
// Good
await kitbase.identify({
  userId: 'usr_8f3a2b',
  traits: { email: 'jane@example.com' }
});

// Bad
await kitbase.identify({
  userId: 'jane@example.com'
});
```

### Update traits when the profile changes

Call `identify()` again whenever user properties change (plan upgrade, name update, etc.) to keep traits current:

```typescript
async function handlePlanUpgrade(newPlan: string) {
  await billingService.upgrade(newPlan);

  await kitbase.identify({
    userId: currentUser.id,
    traits: {
      plan: newPlan,
      upgraded_at: new Date().toISOString()
    }
  });
}
```

### Call reset() on logout

Always call `reset()` when a user logs out to prevent the next user on a shared device from inheriting the previous identity:

```typescript
async function handleLogout() {
  await authService.logout();
  kitbase.reset();
}
```

### Identify as early as possible

Place your `identify()` call at the earliest point after authentication. The longer you wait, the more events are tracked without a `user_id`.

## Next steps

* [Users dashboard guide](/guide/users) — profiles, traits, and identity resolution in the dashboard.
* [Track Events](/track-events) — send custom events for your identified users.
* [JavaScript SDK identity API](/sdks/javascript#user-identity) — `identify()`, `getAnonymousId()`, `reset()`.

---

---
url: 'https://docs.kitbase.dev/proxy.md'
description: >-
  Route analytics requests through your own domain to bypass ad blockers,
  satisfy CSP policies, and keep all traffic on your infrastructure.
---

# Proxy / Custom Domain

Ad blockers and privacy extensions block requests to known analytics domains like `ingest.kitbase.dev`. You can avoid this by proxying analytics requests through your own domain so they appear as first-party traffic.

**Why proxy?**

* **Ad blockers** -- requests to your own domain are not blocked
* **Content Security Policy** -- no need to allowlist a third-party domain
* **Brand consistency** -- all traffic stays on your domain
* **Privacy** -- analytics data never visibly leaves your infrastructure

## How It Works

```
Browser ──► your-domain.com/kb/* ──► ingest.kitbase.dev/*
Browser ──► your-domain.com/lite.js ──► kitbase.dev/lite.js
```

Your proxy sits between the browser and the Kitbase API. The SDK sends requests to your proxy URL, and the proxy forwards them to Kitbase. Two things need proxying:

1. **API endpoints** -- `POST /sdk/v1/logs`, `POST /sdk/v1/logs/batch`, `POST /sdk/v1/identify`
2. **Tracking script** (optional) -- the `lite.js` file loaded via script tag

## SDK Configuration

Point the SDK at your proxy by setting the `baseUrl` option.

### NPM Package

```typescript
import { init } from '@kitbase/analytics';

const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  baseUrl: 'https://your-domain.com/kb',
});
```

### Script Tag

```html
<script>
  window.KITBASE_CONFIG = {
    sdkKey: 'YOUR_SDK_KEY',
    baseUrl: 'https://your-domain.com/kb',
  };
</script>
<script defer src="https://your-domain.com/lite.js"></script>
```

The SDK sends all API requests to `baseUrl` instead of `https://ingest.kitbase.dev`. The `x-sdk-key` header is included automatically -- no changes needed on the auth side.

## Proxy Setup Examples

Every example below does the same two things: forward `your-domain.com/kb/*` to `ingest.kitbase.dev/*`, then point the SDK's `baseUrl` at `/kb`. Pick the one that matches your stack — hosting platforms first, then JavaScript frameworks, web servers, PHP, and hosted CMSs. Whichever you choose, follow the header and caching rules in [Important Notes](#important-notes).

### Vercel

For any project on Vercel (on Next.js, prefer the `next.config.js` rewrite below). Add `vercel.json` at the project root:

```json
{
  "rewrites": [
    { "source": "/kb/:path*", "destination": "https://ingest.kitbase.dev/:path*" }
  ]
}
```

Then set `baseUrl: '/kb'`.

### Netlify

Add a redirect to `netlify.toml` (or `public/_redirects`). Status `200` makes Netlify **proxy** the request instead of redirecting:

```toml
[[redirects]]
  from = "/kb/*"
  to = "https://ingest.kitbase.dev/:splat"
  status = 200
  force = true
```

Then set `baseUrl: '/kb'`. Proxied bytes count toward your Netlify bandwidth.

### Cloudflare Pages

A Pages `_redirects` file can only rewrite to internal assets, so external proxying needs a [Pages Function](https://developers.cloudflare.com/pages/functions/). Create `functions/kb/[[path]].js`:

```js
// functions/kb/[[path]].js
export async function onRequest({ request, params }) {
  const path = (params.path || []).join('/');
  const { search } = new URL(request.url);

  const headers = new Headers(request.headers);
  headers.set('X-Forwarded-For', request.headers.get('CF-Connecting-IP') || '');

  return fetch(`https://ingest.kitbase.dev/${path}${search}`, {
    method: request.method,
    headers,
    body: request.body,
  });
}
```

Then set `baseUrl: '/kb'`.

### Next.js (Rewrites)

Next.js rewrites require zero extra dependencies. Add this to your `next.config.js`:

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  async rewrites() {
    return [
      {
        source: '/kb/:path*',
        destination: 'https://ingest.kitbase.dev/:path*',
      },
    ];
  },
};

module.exports = nextConfig;
```

Then set `baseUrl` to `/kb` (relative URL):

```typescript
const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  baseUrl: '/kb',
});
```

### Nuxt

Nuxt 3 (Nitro) has built-in route-rule proxying — no extra dependencies. In `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  routeRules: {
    '/kb/**': { proxy: 'https://ingest.kitbase.dev/**' },
  },
});
```

Then set `baseUrl: '/kb'`.

### SvelteKit

Add a catch-all server route at `src/routes/kb/[...path]/+server.ts`:

```ts
import type { RequestHandler } from './$types';

const UPSTREAM = 'https://ingest.kitbase.dev';

const proxy: RequestHandler = async ({ request, params, url, getClientAddress }) => {
  const headers = new Headers(request.headers);
  headers.delete('host');           // let fetch set the upstream Host
  headers.delete('content-length'); // recomputed from the forwarded body
  headers.set('X-Forwarded-For', getClientAddress());

  const method = request.method;
  return fetch(`${UPSTREAM}/${params.path}${url.search}`, {
    method,
    headers,
    body: method === 'GET' || method === 'HEAD' ? undefined : await request.text(),
  });
};

export const GET = proxy;
export const POST = proxy;
```

Then set `baseUrl: '/kb'`.

### Astro

Astro needs an SSR adapter (`@astrojs/node`, Vercel, Netlify, …). Add a server endpoint at `src/pages/kb/[...path].ts`:

```ts
import type { APIRoute } from 'astro';

export const prerender = false;

const UPSTREAM = 'https://ingest.kitbase.dev';

export const ALL: APIRoute = async ({ request, params, url }) => {
  const headers = new Headers(request.headers);
  headers.delete('host');
  headers.delete('content-length');

  const method = request.method;
  return fetch(`${UPSTREAM}/${params.path}${url.search}`, {
    method,
    headers,
    body: method === 'GET' || method === 'HEAD' ? undefined : await request.text(),
  });
};
```

Then set `baseUrl: '/kb'`.

### Node.js (Express)

Use `http-proxy-middleware` to forward requests:

```bash
pnpm add http-proxy-middleware
```

```js
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();

app.use(
  '/kb',
  createProxyMiddleware({
    target: 'https://ingest.kitbase.dev',
    changeOrigin: true,
    pathRewrite: { '^/kb': '' },
  })
);

app.listen(3000);
```

### Nginx

```nginx
location /kb/ {
    proxy_pass https://ingest.kitbase.dev/;
    proxy_set_header Host ingest.kitbase.dev;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_ssl_server_name on;
}
```

### Apache

With access to the server config or a `<VirtualHost>` (requires `mod_proxy` + `mod_proxy_http`):

```
SSLProxyEngine On
ProxyPreserveHost Off

ProxyPass        /kb/  https://ingest.kitbase.dev/
ProxyPassReverse /kb/  https://ingest.kitbase.dev/
```

`ProxyPreserveHost Off` sends `ingest.kitbase.dev` as the upstream `Host`, which its TLS termination requires.

On shared hosting where you can only edit `.htaccess`, use the mod\_rewrite proxy flag instead — note `SSLProxyEngine On` must already be set by your host, since it can't live in `.htaccess`:

```
RewriteEngine On
RewriteRule ^kb/(.*)$ https://ingest.kitbase.dev/$1 [P,L]
```

Then set `baseUrl: '/kb'`.

### Caddy

In your `Caddyfile`:

```
your-domain.com {
    handle /kb/* {
        uri strip_prefix /kb
        reverse_proxy https://ingest.kitbase.dev {
            header_up Host ingest.kitbase.dev
        }
    }

    # ... the rest of your site
}
```

Caddy adds `X-Forwarded-For` automatically. Then set `baseUrl: '/kb'`.

### PHP

A minimal `curl`-based proxy script:

```php
<?php
// proxy.php — place at /kb/proxy.php and rewrite /kb/* to this file
$path = ltrim($_SERVER['PATH_INFO'] ?? '', '/');
$url  = 'https://ingest.kitbase.dev/' . $path;

$headers = [];
foreach (getallheaders() as $key => $value) {
    // Forward relevant headers
    $lower = strtolower($key);
    if (in_array($lower, ['content-type', 'x-sdk-key', 'user-agent'])) {
        $headers[] = "$key: $value";
    }
}

// Forward the client IP
$headers[] = 'X-Forwarded-For: ' . $_SERVER['REMOTE_ADDR'];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $_SERVER['REQUEST_METHOD']);

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    curl_setopt($ch, CURLOPT_POSTFIELDS, file_get_contents('php://input'));
}

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);
curl_close($ch);

http_response_code($httpCode);
header('Content-Type: ' . ($contentType ?: 'application/json'));
echo $response;
```

### WordPress

If you control the web server, use the [Nginx](#nginx) or [Apache](#apache) config above — it's the most efficient option. On a managed host where you can only add code, drop a must-use plugin at `wp-content/mu-plugins/kitbase-proxy.php` that streams `/kb/*` to the API:

```php
<?php
// wp-content/mu-plugins/kitbase-proxy.php
add_action('muplugins_loaded', function () {
    $prefix = '/kb/';
    $uri = $_SERVER['REQUEST_URI'] ?? '';
    if (strncmp($uri, $prefix, strlen($prefix)) !== 0) {
        return; // not an analytics request — let WordPress handle it
    }

    $path   = substr(parse_url($uri, PHP_URL_PATH), strlen($prefix));
    $query  = $_SERVER['QUERY_STRING'] ?? '';
    $target = 'https://ingest.kitbase.dev/' . $path . ($query ? "?$query" : '');

    $headers = ['X-Forwarded-For: ' . ($_SERVER['REMOTE_ADDR'] ?? '')];
    if (!empty($_SERVER['CONTENT_TYPE']))    $headers[] = 'Content-Type: ' . $_SERVER['CONTENT_TYPE'];
    if (!empty($_SERVER['HTTP_X_SDK_KEY']))  $headers[] = 'x-sdk-key: ' . $_SERVER['HTTP_X_SDK_KEY'];
    if (!empty($_SERVER['HTTP_USER_AGENT'])) $headers[] = 'User-Agent: ' . $_SERVER['HTTP_USER_AGENT'];

    $ch = curl_init($target);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $_SERVER['REQUEST_METHOD'],
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_POSTFIELDS     => file_get_contents('php://input'),
    ]);
    $body = curl_exec($ch);

    http_response_code(curl_getinfo($ch, CURLINFO_HTTP_CODE));
    header('Content-Type: ' . (curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: 'application/json'));
    curl_close($ch);
    echo $body;
    exit;
});
```

Then set `baseUrl: '/kb'`. Because WordPress starts booting on every analytics request, prefer the server-level proxy whenever you can.

### Cloudflare Workers

```js
export default {
  async fetch(request) {
    const url = new URL(request.url);

    // Rewrite /kb/* → ingest.kitbase.dev/*
    url.hostname = 'ingest.kitbase.dev';
    url.pathname = url.pathname.replace(/^\/kb/, '');

    const headers = new Headers(request.headers);
    headers.set('X-Forwarded-For', request.headers.get('CF-Connecting-IP'));

    return fetch(url.toString(), {
      method: request.method,
      headers,
      body: request.body,
    });
  },
};
```

### AWS CloudFront

CloudFront needs three pieces of configuration:

1. **Add an origin** pointing to `ingest.kitbase.dev` (HTTPS only).
2. **Add a cache behavior** for path pattern `/kb/*` → that origin, with:
   * Cache policy: **CachingDisabled** (analytics requests are all `POST`)
   * Origin request policy: **AllViewerExceptHostHeader** (forwards the visitor's headers and query string, sends the origin's own `Host`)
   * Allowed methods: `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`
3. **Attach a CloudFront Function** (viewer request) to strip the `/kb` prefix, since CloudFront forwards the full path:

```js
function handler(event) {
  var request = event.request;
  request.uri = request.uri.replace(/^\/kb/, '');
  return request;
}
```

CloudFront adds `X-Forwarded-For` automatically. Then set `baseUrl: '/kb'`.

### Shopify, Webflow, Wix & other hosted builders

Fully hosted site builders don't give you a reverse proxy or server config, so you **can't** make analytics requests first-party the way the platforms above do. Two options:

* **Use the standard third-party snippet** (`kitbase.dev/lite.js` + `ingest.kitbase.dev`). It works everywhere; the only cost is that visitors running aggressive blockers aren't counted.
* **Proxy through a subdomain you control.** If your site's DNS is on Cloudflare, run a [Worker](#cloudflare-workers) on a subdomain of your own domain — e.g. `kb.your-domain.com` → `ingest.kitbase.dev` — and set `baseUrl` to `https://kb.your-domain.com`. Because that subdomain is served from your own zone (not a `CNAME` pointed at `kitbase.dev`), it survives the CNAME-uncloaking that uBlock Origin and Firefox apply to bare-CNAME trackers, and it shares your site's registrable domain, so it reads as first-party. Serve the script from the same subdomain too.

## Self-Hosting the Script File

To also proxy the tracking script (`lite.js`), serve it from your domain. This prevents the script tag itself from being blocked.

**Option A: Static file** -- download `https://kitbase.dev/lite.js` and serve it as a static asset. Re-download periodically to pick up SDK updates.

**Option B: Rewrite rule** -- proxy the request like the API:

```nginx
# Nginx
location = /lite.js {
    proxy_pass https://kitbase.dev/lite.js;
    proxy_set_header Host kitbase.dev;
    proxy_ssl_server_name on;
    proxy_cache_valid 200 1h;
}
```

```js
// next.config.js
{
  source: '/lite.js',
  destination: 'https://kitbase.dev/lite.js',
}
```

Then load the script from your domain:

```html
<script defer src="https://your-domain.com/lite.js"></script>
```

## Important Notes

### Forward Client IP Headers

Kitbase uses client IP addresses for geolocation enrichment (country, region, city). Your proxy **must** forward the original client IP so geo data is accurate. The backend reads these headers in order:

* `CF-Connecting-IP` (Cloudflare)
* `X-Forwarded-For` (standard proxy header)
* `X-Real-IP` (Nginx)
* `True-Client-IP` (Akamai)

Most reverse proxies add `X-Forwarded-For` automatically. If yours doesn't, add it explicitly (see the examples above).

### Keep the User-Agent Header

The backend parses `User-Agent` to extract device type, browser, and OS. Make sure your proxy forwards this header unchanged.

### Don't Cache POST Responses

The SDK sends analytics data via `POST` requests. Caching POST responses will cause events to be silently dropped. Only cache `GET` requests (like `lite.js`).

### Update Your Content Security Policy

If you use CSP headers, update `connect-src` to allow your proxy path instead of (or in addition to) `ingest.kitbase.dev`:

```
script-src 'self';
connect-src 'self';
```

Since both the script and API calls come from your own domain, no third-party domains need to be allowlisted.

## Next steps

* [Tracking Script](/tracking-script) — the script the proxy serves from your domain.
* [Web Analytics overview](/web-analytics) — how tracking works end to end.

---

---
url: 'https://docs.kitbase.dev/sdks.md'
description: >-
  Official Kitbase SDKs and tools — JavaScript/TypeScript, React, Angular, the
  MCP server for AI assistants, and the kitbase CLI.
---

# SDKs & Tools

All SDKs share the same core engine and are MIT-licensed ([source on GitHub](https://github.com/scr2em/kitbase-sdk)). The framework packages wrap `@kitbase/analytics` with idiomatic integration — pick the one that matches your stack:

::: tip No build step?
The [tracking script](/tracking-script) is the same SDK, pre-bundled and served from `https://kitbase.dev/lite.js` — ideal for static sites, WordPress, or anywhere you can paste a script tag.
:::

## Tools

* **[CLI](/cli)** — do anything the dashboard can do from your terminal or CI: webhooks, projects, analytics queries, and more, with `--json` output for scripting.
* **[MCP Server](/sdks/mcp)** — connect claude.ai, Claude Code, Cursor, or any MCP-compatible client to your analytics and ask questions in natural language. Hosted at `api.kitbase.dev/mcp` — nothing to install.

## What each SDK covers

Every install path runs the same core engine, so [autocapture](/autocapture) (pageviews, SPA navigations, clicks, scroll depth, sessions), [custom events](/track-events), [identify](/identify-users), offline queuing, and [bot filtering](/crawler-detection#detection-vs-filtering) work identically everywhere. What differs is the integration:

| | Integration style | Build step |
|---|---|---|
| [JavaScript / TypeScript](/sdks/javascript) | `init()` + typed client instance | any bundler |
| [React](/sdks/react) | `KitbaseAnalyticsProvider` + hooks | any bundler |
| [Angular](/sdks/angular) | `provideKitbaseAnalytics` + injectable service | any bundler |
| [Tracking Script](/tracking-script) | `window.KITBASE_CONFIG` + global API | none |

## Next steps

* [Web Analytics overview](/web-analytics) — how capture, filtering, and enrichment fit together.
* [Track Events](/track-events) — channels, tags, notifications, revenue.
* [Error Handling](/error-handling) — error types and retry patterns across all SDKs.

---

---
url: 'https://docs.kitbase.dev/sdks/javascript.md'
description: >-
  Complete reference for the @kitbase/analytics TypeScript SDK. Track events,
  manage user identity, offline queuing, and more.
---

# JavaScript / TypeScript SDK

`@kitbase/analytics` is the core TypeScript SDK for Kitbase analytics. It is fully typed, works in both browser and Node.js environments, and provides a rich API for event tracking, user identity, session management, and offline queuing.

::: tip Two Builds Available
| Build | Import | Size | Notes |
|-------|--------|------|-------|
| **Full** | `@kitbase/analytics` | ~50KB | Includes offline queue (IndexedDB via Dexie) |
| **Lite** | `@kitbase/analytics/lite` | ~12KB | Excludes offline queue |

Use the lite build when you do not need offline support and want a smaller bundle.
:::

## Installation

::: code-group

```bash [pnpm]
pnpm add @kitbase/analytics
```

```bash [npm]
npm install @kitbase/analytics
```

```bash [yarn]
yarn add @kitbase/analytics
```

:::

## Initialization

```typescript
import { init } from '@kitbase/analytics';

const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  debug: false,
  baseUrl: 'https://ingest.kitbase.dev',
  storage: localStorage,
  storageKey: 'kitbase_anonymous_id',
  analytics: {
    autoTrackPageViews: true,
    trackBfcacheRestore: true,
    autoTrackOutboundLinks: true,
    autoTrackClicks: true,
    autoTrackScrollDepth: true,
    autoTrackVisibility: true,
    autoTrackWebVitals: false,
    autoDetectFrustration: true,
  },
  offline: {
    enabled: false,
    maxQueueSize: 1000,
    flushInterval: 30000,
    flushBatchSize: 50,
    maxRetries: 3,
    retryBaseDelay: 1000,
  },
});
```

### Configuration Options

#### Root Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `sdkKey` | `string` | **required** | Your SDK key from the Kitbase dashboard |
| `debug` | `boolean` | `false` | Enable debug logging to the console |
| `baseUrl` | `string` | `'https://ingest.kitbase.dev'` | Ingestion endpoint (override for self-hosted) |
| `storage` | `Storage \| null` | `localStorage` | Storage backend for anonymous ID persistence |
| `storageKey` | `string` | `'kitbase_anonymous_id'` | Key used in storage for the anonymous ID |

#### Analytics Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `autoTrackPageViews` | `boolean` | `true` | Automatically track page views on navigation |
| `trackBfcacheRestore` | `boolean` | `true` | Track a pageview when the browser restores a page from back-forward cache (bfcache). Important for MPA sites where back/forward navigation does not re-execute scripts. |
| `autoTrackOutboundLinks` | `boolean` | `true` | Automatically track clicks on external links |
| `autoTrackClicks` | `boolean` | `true` | Automatically track clicks on interactive elements |
| `autoTrackScrollDepth` | `boolean` | `true` | Automatically track maximum scroll depth per page |
| `autoTrackVisibility` | `boolean` | `true` | Track element visibility via `data-kb-track-visibility` attributes |
| `autoTrackWebVitals` | `boolean` | `false` | Track Core Web Vitals (LCP, CLS, INP, FCP, TTFB) |
| `autoDetectFrustration` | `boolean` | `true` | Detect frustration signals (rage clicks and dead clicks) |

#### Offline Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | `boolean` | `false` | Enable offline queue |
| `maxQueueSize` | `number` | `1000` | Maximum number of events to queue |
| `flushInterval` | `number` | `30000` | Auto-flush interval in milliseconds |
| `flushBatchSize` | `number` | `50` | Number of events per flush batch |
| `maxRetries` | `number` | `3` | Maximum retry attempts for failed events |
| `retryBaseDelay` | `number` | `1000` | Base delay in milliseconds for exponential backoff |

***

## API Reference

### Event Tracking

#### `track(options: TrackOptions): Promise<TrackResponse>`

Track a custom event.

```typescript
const response = await kitbase.track({
  channel: 'payments',
  event: 'New Subscription',
  user_id: 'user-123',
  icon: '💰',
  notify: true,
  description: 'User subscribed to premium plan',
  tags: {
    plan: 'premium',
    cycle: 'monthly',
    amount: 9.99,
  },
});

console.log(response.id);        // "evt_abc123"
console.log(response.timestamp); // "2026-02-13T10:30:00.000Z"
```

#### `trackPageView(options?: PageViewOptions): Promise<TrackResponse>`

Track a page view manually. When `autoTrackPageViews` is enabled, page views are tracked automatically on route changes; use this method for cases where you need explicit control.

```typescript
await kitbase.trackPageView({
  path: '/products/123',
  referrer: 'https://google.com',
  title: 'Product Details',
});

// Or with defaults (uses current window.location and document.title)
await kitbase.trackPageView();
```

#### `trackRevenue(options: RevenueOptions): Promise<TrackResponse>`

Track a revenue event.

```typescript
await kitbase.trackRevenue({
  amount: 99.99,
  currency: 'USD',
  orderId: 'order-123',
  productId: 'prod-456',
  tags: { plan: 'premium' },
});
```

#### `trackOutboundLink(options: OutboundLinkOptions): Promise<TrackResponse>`

Track an outbound link click manually. When `autoTrackOutboundLinks` is enabled, external link clicks are tracked automatically; use this method when you need to track programmatic navigations.

```typescript
await kitbase.trackOutboundLink({
  url: 'https://partner-site.com',
  text: 'Visit Partner',
});
```

***

### User Identity

#### `identify(options: IdentifyOptions): Promise<void>`

Identify a user and link their anonymous activity to a known user ID. Call this immediately after login or signup. The SDK sends the current anonymous ID along with the user ID so the backend can merge the two profiles.

```typescript
await kitbase.identify({
  userId: 'user-123',
  traits: {
    email: 'user@example.com',
    name: 'Jane Doe',
    plan: 'premium',
  },
});
```

::: warning
You must explicitly call `identify()` after authentication. Kitbase does not automatically link anonymous users to identified users.
:::

#### `getAnonymousId(): string`

Get the current anonymous user ID. This is a UUID v4 that is auto-generated and persisted in storage.

```typescript
const anonymousId = kitbase.getAnonymousId();
// => "550e8400-e29b-41d4-a716-446655440000"
```

#### `getUserId(): string | null`

Get the currently identified user ID, or `null` if no user has been identified.

```typescript
const userId = kitbase.getUserId();
// => "user-123" or null
```

#### `reset(): void`

Reset the user identity. Clears the identified user ID, generates a new anonymous ID, and starts a new session.

```typescript
kitbase.reset();
```

***

### Session Management

#### `getSession(): SessionInfo`

Get the current session information.

```typescript
const session = kitbase.getSession();
// => {
//   id: 'sess_abc123',
//   startedAt: 1705321800000,
//   lastActivityAt: 1705323600000
// }
```

#### `getSessionId(): string`

Get the current session ID.

```typescript
const sessionId = kitbase.getSessionId();
// => "sess_abc123"
```

***

### Super Properties

Super properties are key-value pairs that are automatically merged into the `tags` of every event. They are useful for persistent context such as app version, environment, or user segment.

::: warning In-Memory Storage
Super properties are stored in memory and reset when the page reloads. For persistent properties, store them externally and call `register()` on initialization.
:::

#### `register(properties: Record<string, unknown>): void`

Set super properties. If a property already exists, it is overwritten.

```typescript
kitbase.register({
  app_version: '2.1.0',
  environment: 'production',
  platform: 'web',
});
```

#### `registerOnce(properties: Record<string, unknown>): void`

Set super properties only if they are not already set. Useful for values like `first_visit_date` that should never be overwritten.

```typescript
kitbase.registerOnce({
  first_seen: new Date().toISOString(),
});
```

#### `unregister(key: string): void`

Remove a single super property.

```typescript
kitbase.unregister('platform');
```

#### `getSuperProperties(): Record<string, unknown>`

Get all currently registered super properties.

```typescript
const props = kitbase.getSuperProperties();
// => { app_version: '2.1.0', environment: 'production' }
```

#### `clearSuperProperties(): void`

Remove all super properties.

```typescript
kitbase.clearSuperProperties();
```

***

### Timed Events

Start a timer before an action and automatically include the elapsed time as a `$duration` tag (in milliseconds) when the event is tracked.

#### `timeEvent(eventName: string): void`

Start timing an event. When `track()` is later called with the same event name, the `$duration` tag is automatically appended.

```typescript
kitbase.timeEvent('Checkout Completed');

// ... user completes checkout ...

await kitbase.track({
  channel: 'purchases',
  event: 'Checkout Completed',
  tags: { order_id: 'order-123' },
});
// Result: tags include { order_id: 'order-123', $duration: 45000 }
```

#### `cancelTimeEvent(eventName: string): void`

Cancel a running timer without tracking the event.

```typescript
kitbase.cancelTimeEvent('Checkout Completed');
```

#### `getTimedEvents(): string[]`

Get a list of all events that currently have active timers.

```typescript
const activeTimers = kitbase.getTimedEvents();
// => ['Checkout Completed', 'Video Watched']
```

#### `getEventDuration(eventName: string): number`

Get the elapsed time in milliseconds for a timed event without stopping the timer.

```typescript
const elapsed = kitbase.getEventDuration('Video Watched');
// => 45000
```

***

### Offline Queue

When offline mode is enabled, events are queued locally and automatically flushed when the connection is restored. See [Offline Support](#offline-support) for full details.

#### `getQueueStats(): Promise<QueueStats>`

Get statistics about the offline queue.

```typescript
const stats = await kitbase.getQueueStats();
// => { pending: 15, failed: 2, total: 17 }
```

#### `flushQueue(): Promise<void>`

Force send all queued events immediately.

```typescript
await kitbase.flushQueue();
```

#### `clearQueue(): Promise<void>`

Clear all queued events without sending them.

```typescript
await kitbase.clearQueue();
```

***

### Debug & Lifecycle

#### `setDebugMode(enabled: boolean): void`

Toggle debug logging at runtime.

```typescript
kitbase.setDebugMode(true);
```

#### `isDebugMode(): boolean`

Check whether debug mode is currently enabled.

```typescript
if (kitbase.isDebugMode()) {
  console.log('Debug mode is active');
}
```

#### `enableAutoPageViews(): void`

Enable automatic page view tracking after initialization.

```typescript
kitbase.enableAutoPageViews();
```

#### `shutdown(): Promise<void>`

Flush all pending events, clean up timers and listeners, and release resources. Call this when your application unmounts.

```typescript
await kitbase.shutdown();
```

***

## TypeScript Types

### TrackOptions

```typescript
interface TrackOptions {
  /** Category for the event (e.g., "payments", "users") */
  channel: string;
  /** Name of the event (e.g., "New Subscription") */
  event: string;
  /** Identifier for the user */
  user_id?: string;
  /** Emoji or icon name */
  icon?: string;
  /** Send a real-time notification */
  notify?: boolean;
  /** Additional context about the event */
  description?: string;
  /** Key-value metadata */
  tags?: Record<string, unknown>;
}
```

### TrackResponse

```typescript
interface TrackResponse {
  /** Unique event ID (e.g., "evt_abc123") */
  id: string;
  /** Event name */
  event: string;
  /** ISO 8601 timestamp */
  timestamp: string;
}
```

### PageViewOptions

```typescript
interface PageViewOptions {
  /** Page path (defaults to window.location.pathname) */
  path?: string;
  /** Referrer URL (defaults to document.referrer) */
  referrer?: string;
  /** Page title (defaults to document.title) */
  title?: string;
}
```

### RevenueOptions

```typescript
interface RevenueOptions {
  /** Revenue amount */
  amount: number;
  /** Currency code (e.g., "USD") */
  currency?: string;
  /** Order identifier */
  orderId?: string;
  /** Product identifier */
  productId?: string;
  /** Additional metadata */
  tags?: object;
}
```

### OutboundLinkOptions

```typescript
interface OutboundLinkOptions {
  /** Full URL of the outbound link */
  url: string;
  /** Link text content */
  text?: string;
}
```

### IdentifyOptions

```typescript
interface IdentifyOptions {
  /** Unique user identifier */
  userId: string;
  /** User properties (email, name, plan, etc.) */
  traits?: Record<string, unknown>;
}
```

### SessionInfo

```typescript
interface SessionInfo {
  /** Session ID (e.g., "sess_abc123") */
  id: string;
  /** Timestamp when the session started */
  startedAt: number;
  /** Timestamp of the last recorded activity */
  lastActivityAt: number;
}
```

### QueueStats

```typescript
interface QueueStats {
  /** Events waiting to be sent */
  pending: number;
  /** Events that failed and will be retried */
  failed: number;
  /** Total events in queue */
  total: number;
}
```

***

## Error Types

All error classes extend `KitbaseError`, which itself extends the native `Error` class. Import them directly from the package:

```typescript
import {
  KitbaseError,
  AuthenticationError,
  ValidationError,
  TimeoutError,
  ApiError,
} from '@kitbase/analytics';
```

### KitbaseError

Base class for all SDK errors.

```typescript
class KitbaseError extends Error {
  message: string;
}
```

### AuthenticationError

Thrown when the API key is invalid or missing.

```typescript
class AuthenticationError extends KitbaseError {
  message: string; // "Invalid or missing API key"
}
```

**Common causes:** incorrect `sdkKey` value, or an expired or revoked key.

### ValidationError

Thrown when a required field is missing or a field value is invalid.

```typescript
class ValidationError extends KitbaseError {
  message: string; // Error description
  field: string;   // The field that failed validation (e.g., "channel")
}
```

### TimeoutError

Thrown when a request exceeds the 30-second timeout.

```typescript
class TimeoutError extends KitbaseError {
  message: string; // "Request timed out"
}
```

### ApiError

Thrown when the API returns an error response (4xx or 5xx).

```typescript
class ApiError extends KitbaseError {
  message: string;    // Error description from API
  statusCode: number; // HTTP status code (e.g., 429, 500)
  response: unknown;  // Raw response body
}
```

### Error Handling Example

```typescript
import {
  KitbaseError,
  AuthenticationError,
  ValidationError,
  TimeoutError,
  ApiError,
} from '@kitbase/analytics';

try {
  await kitbase.track({
    channel: 'payments',
    event: 'New Subscription',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key - check your sdkKey
    console.error('Authentication failed');
  } else if (error instanceof ValidationError) {
    // Missing required field
    console.error(`Validation error on field: ${error.field}`);
  } else if (error instanceof TimeoutError) {
    // Request timed out - safe to retry
    console.error('Request timed out');
  } else if (error instanceof ApiError) {
    // API returned an error
    console.error(`API error ${error.statusCode}:`, error.response);
  } else if (error instanceof KitbaseError) {
    // Generic SDK error
    console.error(error.message);
  }
}
```

### Retry with Exponential Backoff

```typescript
import type { TrackOptions, TrackResponse, KitbaseAnalytics } from '@kitbase/analytics';
import {
  AuthenticationError,
  ValidationError,
  TimeoutError,
  ApiError,
} from '@kitbase/analytics';

async function trackWithRetry(
  kitbase: KitbaseAnalytics,
  options: TrackOptions,
  retries = 3
): Promise<TrackResponse> {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      return await kitbase.track(options);
    } catch (error) {
      // Never retry auth or validation errors
      if (error instanceof AuthenticationError) throw error;
      if (error instanceof ValidationError) throw error;

      const shouldRetry =
        error instanceof TimeoutError ||
        (error instanceof ApiError && error.statusCode >= 500);

      if (shouldRetry && attempt < retries) {
        const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }

      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}
```

***

## Framework Examples

### React

```typescript
import { init } from '@kitbase/analytics';
import { useEffect } from 'react';

// Initialize once outside of components
const kitbase = init({ sdkKey: 'YOUR_SDK_KEY' });

function App() {
  const { user } = useAuth();

  // Identify the user after authentication
  useEffect(() => {
    if (user) {
      kitbase.identify({
        userId: user.id,
        traits: {
          email: user.email,
          name: user.name,
          plan: user.plan,
        },
      });
    }
  }, [user]);

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      kitbase.shutdown();
    };
  }, []);

  return <YourApp />;
}

// Track custom events anywhere in your app
function ExportButton() {
  const handleExport = async () => {
    kitbase.timeEvent('Export Generated');

    await generateExport();

    await kitbase.track({
      channel: 'engagement',
      event: 'Export Generated',
      tags: { format: 'pdf' },
    });
  };

  return <button onClick={handleExport}>Export PDF</button>;
}
```

### Next.js

```typescript
'use client';

import { init } from '@kitbase/analytics';
import { useEffect } from 'react';

// Initialize on the client side only
const kitbase =
  typeof window !== 'undefined'
    ? init({ sdkKey: 'YOUR_SDK_KEY' })
    : null;

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
  const { user } = useAuth();

  useEffect(() => {
    if (user && kitbase) {
      kitbase.identify({
        userId: user.id,
        traits: { email: user.email },
      });
    }
  }, [user]);

  useEffect(() => {
    return () => {
      kitbase?.shutdown();
    };
  }, []);

  return <>{children}</>;
}

// Export for use across your app
export { kitbase };
```

```typescript
// app/layout.tsx
import { AnalyticsProvider } from './analytics-provider';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AnalyticsProvider>{children}</AnalyticsProvider>
      </body>
    </html>
  );
}
```

### Vue

```typescript
// plugins/kitbase.ts
import { init } from '@kitbase/analytics';

const kitbase = init({ sdkKey: 'YOUR_SDK_KEY' });

export default {
  install(app) {
    app.provide('kitbase', kitbase);
    app.config.globalProperties.$kitbase = kitbase;
  },
};

export { kitbase };
```

```typescript
// main.ts
import { createApp } from 'vue';
import kitbasePlugin from './plugins/kitbase';
import App from './App.vue';

const app = createApp(App);
app.use(kitbasePlugin);
app.mount('#app');
```

```vue
<!-- components/ExportButton.vue -->
<script setup lang="ts">
import { inject } from 'vue';
import type { KitbaseAnalytics } from '@kitbase/analytics';

const kitbase = inject<KitbaseAnalytics>('kitbase')!;

async function handleExport() {
  await kitbase.track({
    channel: 'engagement',
    event: 'Export Generated',
    tags: { format: 'csv' },
  });
}
</script>

<template>
  <button @click="handleExport">Export CSV</button>
</template>
```

### Nuxt

```typescript
// plugins/kitbase.client.ts
import { init } from '@kitbase/analytics';

export default defineNuxtPlugin(() => {
  const kitbase = init({ sdkKey: 'YOUR_SDK_KEY' });

  return {
    provide: {
      kitbase,
    },
  };
});
```

```vue
<!-- pages/index.vue -->
<script setup lang="ts">
const { $kitbase } = useNuxtApp();

async function onSignUp() {
  await $kitbase.identify({ userId: 'user-123' });
  await $kitbase.track({
    channel: 'users',
    event: 'User Signed Up',
    icon: '👤',
    notify: true,
  });
}
</script>
```

***

## Offline Support

### How It Works

When offline mode is enabled, the SDK queues events locally when the network is unavailable and automatically flushes them when the connection is restored.

```
User action
    |
track() called
    |
+------------------+
| Online?          |
+------------------+
    |          |
   Yes         No
    |          |
Send to     Queue in
  API       IndexedDB
    |          |
    |    +----------+
    |    | Network  | <-- 'online' event
    |    | restored |
    |    +----------+
    |          |
    |     Flush queue
    |          |
   Done       Done
```

### Enabling Offline Mode

```typescript
const kitbase = init({
  sdkKey: 'YOUR_SDK_KEY',
  offline: {
    enabled: true,
    maxQueueSize: 1000,
    flushInterval: 30000,
    flushBatchSize: 50,
    maxRetries: 3,
    retryBaseDelay: 1000,
  },
});
```

::: tip Full Build Required
Offline mode requires the full build (`@kitbase/analytics`). The lite build (`@kitbase/analytics/lite`) does not include offline queue support.
:::

### Retry Logic

Failed events are retried with exponential backoff. The delay is calculated as `retryBaseDelay * 2^attempt`:

| Attempt | Delay | Action |
|---------|-------|--------|
| 1st retry | 1 second | Retry |
| 2nd retry | 2 seconds | Retry |
| 3rd retry | 4 seconds | Retry |
| After max retries | -- | Event dropped |

### Storage

| Environment | Backend | Persistence |
|-------------|---------|-------------|
| Browser | IndexedDB via Dexie | Events survive page reloads and browser restarts |
| Node.js | In-memory | Events are lost on process restart |

### Queue Management

```typescript
// Check queue health
const stats = await kitbase.getQueueStats();
if (stats.pending > 0) {
  showOfflineIndicator();
}

// Force flush (e.g., before navigation)
await kitbase.flushQueue();

// Clear queue (e.g., discard pending events)
await kitbase.clearQueue();
```

### Progressive Web App Integration

```typescript
// Flush on service worker sync
self.addEventListener('sync', async (event) => {
  if (event.tag === 'kitbase-sync') {
    event.waitUntil(kitbase.flushQueue());
  }
});
```

::: warning Queue Overflow
When the queue reaches `maxQueueSize`, new events are dropped. Monitor `getQueueStats()` for critical applications.
:::

***

## Bot Filtering

Kitbase automatically filters out bot and crawler traffic. Events are not sent when your app is visited by headless browsers (Puppeteer, Playwright), automated testing tools (Selenium, WebDriver), HTTP clients (curl, wget), search engine crawlers (Googlebot, Bingbot), or social media crawlers (Facebook, Twitter, Slack). No configuration is required.

Filtering keeps bots **out** of your analytics. To **see** bot and crawler traffic instead — which AI crawlers and search engines visit your site — use the separate [Bot & Crawler Detection](/crawler-detection) feature ([detection vs. filtering](/crawler-detection#detection-vs-filtering)).

***

## Auto-Tracked Events

When auto-tracking is enabled (the default), the SDK fires the following events on the internal `__analytics` channel:

| Event | Config Flag | Trigger |
|-------|-------------|---------|
| `screen_view` | `autoTrackPageViews` | Page load, `pushState`, `popstate` |
| `screen_view` | `trackBfcacheRestore` | Page restored from bfcache (back/forward in MPAs) |
| `outbound_link` | `autoTrackOutboundLinks` | Click on external link |
| `click` | `autoTrackClicks` | Click on interactive element |
| `scroll_depth` | `autoTrackScrollDepth` | Page unload (reports max scroll %) |
| `rage_click` | `autoDetectFrustration` | 3+ clicks within 1s in same area |
| `dead_click` | `autoDetectFrustration` | Click with no DOM change within 1s |
| `web_vitals` | `autoTrackWebVitals` | Once per page load (opt-in) |
| `revenue` | -- | Explicit `trackRevenue()` call |

### Data Attributes (No-Code Tracking)

Track events from HTML without writing JavaScript by annotating elements with data attributes:

```html
<!-- Track a named click event -->
<button data-kb-track-click="CTA Clicked">Sign Up Now</button>

<!-- Track with a custom channel -->
<button
  data-kb-track-click="Add to Cart"
  data-kb-click-channel="ecommerce"
>
  Add to Cart
</button>

<!-- Track element visibility duration -->
<section data-kb-track-visibility="Pricing Section Viewed">
  ...
</section>

<!-- Visibility with custom threshold and channel -->
<div
  data-kb-track-visibility="Hero Banner Viewed"
  data-kb-visibility-channel="marketing"
  data-kb-visibility-threshold="0.75"
>
  ...
</div>
```

For the complete auto-tracked events reference, see [Autocapture](/autocapture).

***

## Best Practices

### Initialize Once, Reuse Everywhere

Create a single instance with `init()` and export it for use across your application. Do not create multiple instances.

```typescript
// lib/kitbase.ts
import { init } from '@kitbase/analytics';

export const kitbase = init({ sdkKey: 'YOUR_SDK_KEY' });
```

```typescript
// Anywhere in your app
import { kitbase } from '@/lib/kitbase';

await kitbase.track({ channel: 'engagement', event: 'Feature Used' });
```

### Use Consistent Channel Naming

Use lowercase, plural nouns for channel names:

| Channel | Use Case |
|---------|----------|
| `payments` | Subscriptions, purchases, refunds |
| `users` | Signups, logins, profile updates |
| `errors` | Application errors, exceptions |
| `features` | Feature usage tracking |
| `engagement` | General user interactions |
| `system` | Deployments, server events |

### Leverage Auto-Tracking

Prefer auto-tracking over manual tracking wherever possible. The SDK handles page views, sessions, outbound links, clicks, and scroll depth automatically. Reserve manual `track()` calls for business-specific events like purchases, signups, and feature usage.

### Handle Errors Gracefully

Never let tracking failures break your application. Wrap calls in a safe helper:

```typescript
async function safeTrack(options: TrackOptions): Promise<void> {
  try {
    await kitbase.track(options);
  } catch (error) {
    // Log but don't throw - tracking is non-critical
    console.error('Event tracking failed:', error);
  }
}
```

### Call shutdown() on Unmount

Always call `shutdown()` when your application unmounts to ensure all queued events are sent and resources are released:

```typescript
// React
useEffect(() => {
  return () => {
    kitbase.shutdown();
  };
}, []);

// Vanilla JS
window.addEventListener('beforeunload', () => {
  kitbase.shutdown();
});
```

### Use Super Properties for Shared Context

Set properties like app version and environment once via `register()` instead of passing them on every `track()` call:

```typescript
kitbase.register({
  app_version: '2.1.0',
  environment: process.env.NODE_ENV,
});

// All subsequent events automatically include these tags
await kitbase.track({ channel: 'users', event: 'Signup' });
// tags: { app_version: '2.1.0', environment: 'production', ... }
```

### Use snake\_case for Tag Keys

```typescript
// Good
tags: { user_type: 'premium', error_code: 'E001' }

// Bad
tags: { UserType: 'premium', 'error-code': 'E001' }
```

***

## Next Steps

* [Analytics Dashboard](/guide/analytics) -- Dashboard metrics, breakdowns, and filtering
* [Autocapture](/autocapture) -- Complete reference for every automatic event
* [Custom Events](/track-events) -- Channels, tags, notifications, and use cases
* [Identify Users](/identify-users) -- Anonymous tracking and identity resolution
* [Error Handling](/error-handling) -- Full error handling reference for all SDKs
* [Analytics Guide](/guide/analytics) -- Privacy, bot filtering, and data enrichment

---

---
url: 'https://docs.kitbase.dev/sdks/react.md'
description: >-
  Integrate Kitbase analytics into React apps with KitbaseAnalyticsProvider and
  hooks.
---

# React Integration

The `@kitbase/analytics-react` package wraps the core SDK with a React Context provider and a set of hooks for idiomatic React usage.

::: tip React 17+
The package uses the `react-jsx` transform and requires React 17 or later.
:::

## Installation

::: code-group

```bash [pnpm]
pnpm add @kitbase/analytics-react
```

```bash [npm]
npm install @kitbase/analytics-react
```

```bash [yarn]
yarn add @kitbase/analytics-react
```

:::

## Setup

Wrap your application with `KitbaseAnalyticsProvider`. The SDK initializes eagerly so auto-tracking is active immediately.

```tsx
// main.tsx / App.tsx
import { KitbaseAnalyticsProvider } from '@kitbase/analytics-react';

function App() {
  return (
    <KitbaseAnalyticsProvider config={{ sdkKey: 'YOUR_SDK_KEY' }}>
      <YourApp />
    </KitbaseAnalyticsProvider>
  );
}
```

::: info
SDK keys are public and safe to commit to source control. They are used only to identify which project to send traffic to and do not grant access to your data.
:::

### Configuration Options

All options beyond `sdkKey` are optional. Sensible defaults are applied automatically.

```tsx
<KitbaseAnalyticsProvider
  config={{
    sdkKey: 'YOUR_SDK_KEY',
    debug: false,

    analytics: {
      autoTrackPageViews: true,       // Tracks pushState / popstate navigations
      autoTrackClicks: true,          // Tracks clicks on interactive elements
      autoTrackOutboundLinks: true,   // Tracks clicks on external links
      autoTrackScrollDepth: true,     // Tracks max scroll depth per page
      autoTrackVisibility: true,      // Tracks element visibility via data attributes
      autoTrackWebVitals: false,      // Requires 'web-vitals' package
      autoDetectFrustration: true,    // Detects rage clicks and dead clicks
    },

    offline: {
      enabled: false,
      maxQueueSize: 1000,
      flushInterval: 30000,           // 30 seconds
      flushBatchSize: 50,
      maxRetries: 3,
    },

    botDetection: {
      enabled: true,
    },
  }}
>
  <YourApp />
</KitbaseAnalyticsProvider>
```

## Auto-Tracking

Everything below is enabled by default — no manual wiring needed. The SDK patches `history.pushState` and listens for `popstate`, so React Router navigations are captured automatically.

| Feature | Config Key | What It Tracks |
|---|---|---|
| Page views | `autoTrackPageViews` | Initial load + SPA navigations (pushState / popstate) |
| Clicks | `autoTrackClicks` | Clicks on buttons, links, inputs, and other interactive elements |
| Outbound links | `autoTrackOutboundLinks` | Clicks on links to external domains |
| Scroll depth | `autoTrackScrollDepth` | Maximum scroll percentage per page |
| Element visibility | `autoTrackVisibility` | Time an element is visible in the viewport (via data attributes) |
| Frustration signals | `autoDetectFrustration` | Rage clicks (3+ rapid clicks) and dead clicks (no DOM change) |
| Web Vitals | `autoTrackWebVitals` | LCP, CLS, INP, FCP, TTFB (requires `web-vitals` package) |

### Data Attributes

Use data attributes for declarative tracking without writing JavaScript.

**Click tracking** — fires a custom event when the element is clicked:

```tsx
<button data-kb-track-click="CTA Clicked"
        data-kb-click-channel="marketing">
  Sign Up
</button>
```

**Visibility tracking** — measures how long an element is visible in the viewport:

```tsx
<div data-kb-track-visibility="Pricing Section Viewed"
     data-kb-visibility-channel="marketing"
     data-kb-visibility-threshold="0.75">
  Pricing details...
</div>
```

| Attribute | Description |
|---|---|
| `data-kb-track-click` | Event name fired on click |
| `data-kb-click-channel` | Channel for the click event (default: `'engagement'`) |
| `data-kb-track-visibility` | Event name fired when element leaves viewport |
| `data-kb-visibility-channel` | Channel for the visibility event (default: `'engagement'`) |
| `data-kb-visibility-threshold` | IntersectionObserver threshold 0–1 (default: `0.5`) |

## Using the Hooks

All hooks must be called inside a component wrapped by `KitbaseAnalyticsProvider`.

```tsx
import { useTrack, useIdentify, useRevenue } from '@kitbase/analytics-react';

function Checkout({ order }: { order: Order }) {
  const track = useTrack();
  const identify = useIdentify();
  const trackRevenue = useRevenue();

  async function onPurchase() {
    await track({
      channel: 'payments',
      event: 'Purchase Completed',
      tags: { amount: order.total, items: order.items.length },
    });

    await trackRevenue({
      amount: order.total,
      currency: order.currency,
    });
  }

  return <button onClick={onPurchase}>Complete Purchase</button>;
}
```

## Hooks Reference

### Event Tracking

#### `useTrack()`

Returns a memoized function to track custom events.

```tsx
const track = useTrack();
track({ channel: 'ui', event: 'Button Clicked', tags: { location: 'header' } });
```

#### `usePageView()`

Returns a memoized function to track page views manually.

```tsx
const trackPageView = usePageView();
// Usually automatic — call manually only if needed
trackPageView({ path: '/custom-path' });
```

#### `useAutoPageView(options?, deps?)`

Automatically tracks a page view on mount and whenever `deps` change.

```tsx
function ProductPage({ productId }: { productId: string }) {
  useAutoPageView(
    { tags: { product_id: productId } },
    [productId]
  );

  return <div>Product {productId}</div>;
}
```

#### `useRevenue()`

Returns a memoized function to track revenue events.

```tsx
const trackRevenue = useRevenue();
trackRevenue({ amount: 1999, currency: 'USD', tags: { plan: 'premium' } });
```

### User Identity

#### `useIdentify()`

Returns a memoized function to identify users.

```tsx
const identify = useIdentify();
await identify({
  userId: 'user_123',
  traits: { email: 'user@example.com', plan: 'premium' },
});
```

See [Identify Users](/identify-users) for more on how identity resolution works.

#### `useUserId()`

Returns the current identified user ID, or `null`.

```tsx
const userId = useUserId();
```

#### `useReset()`

Returns a function to clear the user identity (typically on logout).

```tsx
const reset = useReset();
reset();
```

### Super Properties

#### `useSuperProperties(properties, deps?)`

Registers properties that are included in every subsequent event. Re-registers when `deps` change.

```tsx
function App({ user }: { user: User }) {
  useSuperProperties(
    { user_type: user.type, plan: user.plan },
    [user.type, user.plan]
  );

  return <MainContent />;
}
```

For `registerOnce`, `unregister`, `getSuperProperties`, and `clearSuperProperties`, use the instance directly via `useKitbaseAnalytics()`.

### Time Events

#### `useTimeEvent(eventName)`

Returns an object with `start`, `stop`, and `getDuration` to measure event duration.

```tsx
function VideoPlayer() {
  const { start } = useTimeEvent('Video Watched');
  const track = useTrack();

  return (
    <video
      onPlay={start}
      onEnded={() => track({
        channel: 'engagement',
        event: 'Video Watched',
        // $duration automatically included
      })}
    />
  );
}
```

### Direct Instance Access

For features not covered by the convenience hooks (plugins, debug mode, timed event listing, etc.), use `useKitbaseAnalytics()` to get the raw `KitbaseAnalytics` instance.

```tsx
import { useKitbaseAnalytics, WebVitalsPlugin } from '@kitbase/analytics-react';

function PluginLoader() {
  const kitbase = useKitbaseAnalytics();

  useEffect(() => {
    kitbase.use(new WebVitalsPlugin());
  }, [kitbase]);

  return null;
}
```

Available instance methods include `register`, `registerOnce`, `unregister`, `getSuperProperties`, `clearSuperProperties`, `timeEvent`, `getTimedEvents`, `getEventDuration`, `cancelTimeEvent`, `trackOutboundLink`, `use`, `getPlugins`, `setDebugMode`, `isDebugMode`, `shutdown`, and `getInstance`. See the [JavaScript SDK](/sdks/javascript) for full details.

### Re-exported Types

All types, errors, and utilities from `@kitbase/analytics` are re-exported, so you can import everything from a single package:

```tsx
import {
  type KitbaseConfig,
  type TrackOptions,
  type TrackResponse,
  type PageViewOptions,
  type RevenueOptions,
  type IdentifyOptions,
  type KitbasePlugin,
  KitbaseError,
  ValidationError,
} from '@kitbase/analytics-react';
```

## Next Steps

* [Autocapture](/autocapture) — Full reference of automatically tracked events
* [Custom Events](/track-events) — Channels, tags, and notifications
* [Identify Users](/identify-users) — Identity resolution and user properties
* [JavaScript SDK](/sdks/javascript) — Full SDK reference including offline support

---

---
url: 'https://docs.kitbase.dev/sdks/angular.md'
description: >-
  Integrate Kitbase analytics into Angular apps with provideKitbaseAnalytics and
  the injectable KitbaseAnalyticsService.
---

# Angular Integration

The `@kitbase/analytics-angular` package wraps the core SDK with Angular-native dependency injection via `provideKitbaseAnalytics()` and an injectable `KitbaseAnalyticsService`.

::: tip Standalone-First
The package uses `provideKitbaseAnalytics()` which works with standalone Angular applications (Angular 14+). No `NgModule` is required.
:::

## Installation

::: code-group

```bash [pnpm]
pnpm add @kitbase/analytics-angular
```

```bash [npm]
npm install @kitbase/analytics-angular
```

```bash [yarn]
yarn add @kitbase/analytics-angular
```

:::

## Setup

Register the provider in your application config. The SDK initializes eagerly at bootstrap so auto-tracking is active immediately.

```typescript
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKitbaseAnalytics({
      sdkKey: 'YOUR_SDK_KEY',
    }),
  ],
};
```

::: info
SDK keys are public and safe to commit to source control. They are used only to identify which project to send traffic to and do not grant access to your data.
:::

### Configuration Options

All options beyond `sdkKey` are optional. Sensible defaults are applied automatically.

```typescript
provideKitbaseAnalytics({
  sdkKey: 'YOUR_SDK_KEY',
  debug: false,

  analytics: {
    autoTrackPageViews: true,       // Tracks pushState / popstate navigations
    autoTrackClicks: true,          // Tracks clicks on interactive elements
    autoTrackOutboundLinks: true,   // Tracks clicks on external links
    autoTrackScrollDepth: true,     // Tracks max scroll depth per page
    autoTrackVisibility: true,      // Tracks element visibility via data attributes
    autoTrackWebVitals: false,      // Requires 'web-vitals' package
    autoDetectFrustration: true,    // Detects rage clicks and dead clicks
  },

  offline: {
    enabled: false,
    maxQueueSize: 1000,
    flushInterval: 30000,           // 30 seconds
    flushBatchSize: 50,
    maxRetries: 3,
  },

  botDetection: {
    enabled: true,
  },
});
```

## Auto-Tracking

Everything below is enabled by default — no manual wiring needed. The SDK patches `history.pushState` and listens for `popstate`, so Angular Router navigations are captured automatically.

| Feature | Config Key | What It Tracks |
|---|---|---|
| Page views | `autoTrackPageViews` | Initial load + SPA navigations (pushState / popstate) |
| Clicks | `autoTrackClicks` | Clicks on buttons, links, inputs, and other interactive elements |
| Outbound links | `autoTrackOutboundLinks` | Clicks on links to external domains |
| Scroll depth | `autoTrackScrollDepth` | Maximum scroll percentage per page |
| Element visibility | `autoTrackVisibility` | Time an element is visible in the viewport (via data attributes) |
| Frustration signals | `autoDetectFrustration` | Rage clicks (3+ rapid clicks) and dead clicks (no DOM change) |
| Web Vitals | `autoTrackWebVitals` | LCP, CLS, INP, FCP, TTFB (requires `web-vitals` package) |

### Data Attributes

Use data attributes for declarative tracking without writing TypeScript.

**Click tracking** — fires a custom event when the element is clicked:

```html
<button data-kb-track-click="CTA Clicked"
        data-kb-click-channel="marketing">
  Sign Up
</button>
```

**Visibility tracking** — measures how long an element is visible in the viewport:

```html
<div data-kb-track-visibility="Pricing Section Viewed"
     data-kb-visibility-channel="marketing"
     data-kb-visibility-threshold="0.75">
  Pricing details...
</div>
```

| Attribute | Description |
|---|---|
| `data-kb-track-click` | Event name fired on click |
| `data-kb-click-channel` | Channel for the click event (default: `'engagement'`) |
| `data-kb-track-visibility` | Event name fired when element leaves viewport |
| `data-kb-visibility-channel` | Channel for the visibility event (default: `'engagement'`) |
| `data-kb-visibility-threshold` | IntersectionObserver threshold 0–1 (default: `0.5`) |

## Using the Service

Inject `KitbaseAnalyticsService` into any component or service.

```typescript
import { Component, inject } from '@angular/core';
import { KitbaseAnalyticsService } from '@kitbase/analytics-angular';

@Component({ selector: 'app-checkout', templateUrl: './checkout.component.html' })
export class CheckoutComponent {
  private kitbase = inject(KitbaseAnalyticsService);

  async onPurchase(order: Order): Promise<void> {
    await this.kitbase.track({
      channel: 'payments',
      event: 'Purchase Completed',
      tags: { amount: order.total, items: order.items.length },
    });

    await this.kitbase.trackRevenue({
      amount: order.total,
      currency: order.currency,
    });
  }
}
```

## API Reference

### Event Tracking

```typescript
// Custom event
kitbase.track({ channel: 'ui', event: 'Button Clicked', tags: { location: 'header' } });

// Page view (usually automatic — call manually only if needed)
kitbase.trackPageView({ path: '/custom-path' });

// Revenue
kitbase.trackRevenue({ amount: 1999, currency: 'USD', tags: { plan: 'premium' } });

// Outbound link
kitbase.trackOutboundLink({ url: 'https://example.com', text: 'Visit Example' });
```

### User Identity

```typescript
// Identify after login
await kitbase.identify({
  userId: 'user_123',
  traits: { email: 'user@example.com', plan: 'premium' },
});

// Get current user ID
const id = kitbase.getUserId(); // string | null

// Clear identity on logout
kitbase.reset();
```

See [Identify Users](/identify-users) for more on how identity resolution works.

### Super Properties

Attach properties to every subsequent event automatically.

```typescript
// Merge properties into all future events
kitbase.register({ app_version: '2.4.1', platform: 'web' });

// Set only if not already registered
kitbase.registerOnce({ initial_referrer: document.referrer });

// Remove a single property
kitbase.unregister('platform');

// Read or clear all
kitbase.getSuperProperties();
kitbase.clearSuperProperties();
```

### Time Events

Measure duration between two points.

```typescript
// Start a timer
kitbase.timeEvent('Checkout Flow');

// ... user completes checkout ...

// The next track() call for this event name automatically includes the duration
await kitbase.track({ channel: 'conversions', event: 'Checkout Flow' });

// Other helpers
kitbase.getTimedEvents();                 // string[]
kitbase.getEventDuration('Checkout Flow'); // number | null (ms)
kitbase.cancelTimeEvent('Checkout Flow');  // stop without tracking
```

### Plugins

```typescript
kitbase.use(myPlugin);        // Register a plugin
kitbase.getPlugins();         // string[] — active plugin names
```

### Utilities

```typescript
kitbase.setDebugMode(true);   // Enable console logging
kitbase.isDebugMode();        // boolean
kitbase.shutdown();           // Cleanup and stop all tracking
kitbase.getInstance();        // Access the underlying core SDK instance
```

## Next Steps

* [Autocapture](/autocapture) — Full reference of automatically tracked events
* [Custom Events](/track-events) — Channels, tags, and notifications
* [Identify Users](/identify-users) — Identity resolution and user properties
* [JavaScript SDK](/sdks/javascript) — Full SDK reference including offline support

---

---
url: 'https://docs.kitbase.dev/sdks/mcp.md'
description: >-
  Connect your AI assistant to Kitbase analytics over the hosted MCP server —
  nothing to install. Query visitors, events, users, sessions, funnels,
  retention, AI visibility, and bot traffic — and manage AI-visibility tracking,
  site audits, webhooks, workflows, and your team — from claude.ai, Claude Code,
  Cursor, or any MCP-compatible client.
---

# MCP Server

Kitbase speaks [MCP (Model Context Protocol)](https://modelcontextprotocol.io). Connect it to claude.ai, Claude Code, Cursor, or any MCP-compatible client and ask questions about your traffic, events, users, sessions, AI visibility, and bot traffic in natural language. Over an OAuth connection it also exposes [management tools](#management-tools) — add AI-visibility competitors and prompts, start scans and site audits, build workflows, manage webhooks and team members.

The server is **built into the Kitbase API** — there is nothing to install or run.

```
https://api.kitbase.dev/mcp
```

Self-hosted deployments serve the same endpoint at `https://<your-host>/api/mcp`.

::: tip No Dashboard Required
Once connected, your AI assistant can answer questions like "How many visitors are on the site right now?" or "Which domains does ChatGPT cite instead of us?" by querying Kitbase directly — and, on an OAuth connection, act on requests like "Add Vercel as a competitor we track in AI answers."
:::

## Authentication

The server accepts two kinds of credentials. Both are scoped to exactly **one project** — tools default to it, so no organization parameter is ever needed (project-scoped tools do accept an optional `projectId` to target another project in the same organization).

| Method | Best for | How |
|--------|----------|-----|
| **OAuth** | claude.ai / Claude Desktop connectors | Add the server URL as a custom connector; a browser window asks you to sign in and pick the org + project to grant access to |
| **Private API key** | Cursor, headless clients | Send `Authorization: Bearer sk_kitbase_...` (or `X-API-Key`) with each request |

Read tools work with either credential. **[Management tools](#management-tools) work only over OAuth**: each one checks the signed-in user's live permission (the same permission the dashboard enforces, capped by what the connection was granted). A private API key carries no user to check, so key-authenticated calls to management tools are rejected.

::: warning
Private API keys (`sk_kitbase_`) are secret keys — not the public SDK token used in browser SDKs. Generate one in your Kitbase dashboard under **Project Settings > API Keys**.
:::

### Revoking a connection

Revoke an OAuth connection from the dashboard under **Account Settings → MCP Connections**. Revocation takes effect on the connection's next token refresh, and the connection cannot renew itself afterwards.

Refresh tokens rotate on every use and are single-use. If a rotated token is ever presented again — the signature of a copied credential — the whole connection is revoked immediately rather than renewed, so a leaked token buys at most one refresh before both parties are cut off. Nothing is required of you for that to happen.

## Client Setup

### claude.ai (web / desktop)

1. Go to **Settings > Connectors > Add custom connector**
2. Enter `https://api.kitbase.dev/mcp`
3. Complete the sign-in flow and choose the organization and project to connect

### Claude Code

```bash
claude mcp add --transport http kitbase https://api.kitbase.dev/mcp \
  --header "Authorization: Bearer sk_kitbase_your_key_here"
```

### Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "kitbase": {
      "url": "https://api.kitbase.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_kitbase_your_key_here"
      }
    }
  }
}
```

### Other MCP Clients

The server speaks the standard MCP Streamable HTTP transport. Any client that supports remote MCP servers works — point it at the URL and supply either credential.

## Discovery

Clients and agents that look for MCP servers automatically, rather than being handed a URL, find Kitbase through the standard discovery documents. None of them require authentication.

| Document | URL | Media type |
|----------|-----|------------|
| **Server card** — name, version, description, transport, how to authenticate ([SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)) | `https://api.kitbase.dev/mcp/server-card` | `application/mcp-server-card+json` |
| **AI catalog** — the domain-level index that points at the server card | `https://kitbase.dev/.well-known/ai-catalog.json` and `https://api.kitbase.dev/.well-known/ai-catalog.json` | `application/ai-catalog+json` |
| **Protected-resource metadata** — which authorization server protects `/mcp` ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)) | `https://api.kitbase.dev/.well-known/oauth-protected-resource/mcp` | `application/json` |
| **Authorization-server metadata** — authorize/token/revocation endpoints, PKCE, `scopes_supported` ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) | `https://api.kitbase.dev/.well-known/oauth-authorization-server` | `application/json` |

An unauthenticated request to `/mcp` is answered with `401` and a `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"` header, which is how an OAuth-aware client finds its way to the consent flow without any configuration. The server card carries the same facts in one place:

```bash
curl -s -H "Accept: application/mcp-server-card+json" https://api.kitbase.dev/mcp/server-card | jq '.remotes[0]'
```

The card deliberately does not list tools — they depend on what the connection was granted, so clients read them at runtime with `tools/list`. The REST side of the same platform is described by the [OpenAPI spec](/api-reference#openapi-specification), which also documents `POST /mcp` with its OAuth security scheme.

## Available Tools

The server exposes **180 tools**. Most are reads for querying analytics, reports and configuration; the rest are [management tools](#management-tools) that change configuration — AI-visibility setup and runs, site audits, webhooks, projects, team, and [workflows](#workflows). Analytics data itself (events, sessions, visitors) can never be modified or deleted through MCP.

The tables below cover the tools you are most likely to reach for. Your client's own tool list is the complete one — ask your assistant to list the Kitbase tools if you want to see everything it has.

Unless noted otherwise, every tool accepts the standard date parameters described in [Date Filtering](#date-filtering): `preset`, `from` and `to`.

### Web Analytics

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `get_web_summary` | Summary KPIs — visitors, pageviews, bounce rate, average duration | `filters` |
| `get_web_timeline` | Visitors/pageviews as a time series | `interval` (`hour`/`day`/`week`/`month`), `filters` |
| `get_web_breakdown` | Break down by dimension (`COUNTRY`, `BROWSER`, `OS`, `DEVICE`, `PATH`, `REFERRER`, …) | `dimension` (required), `page`, `size`, `filters` |

All three also take the [period comparison](#period-comparison) parameters, so "how does this week compare to last?" is one call rather than two.

`dimension` is a closed set, and the tool schema lists it, so an assistant picks from
it rather than guessing. There is no `page` dimension — pages are `PATH`, `ENTRY_PAGE`,
`EXIT_PAGE` and `TOP_PAGE`. The full set:

`DEVICE`, `BROWSER`, `BROWSER_VERSION`, `OS`, `OS_VERSION`, `BRAND`, `MODEL`,
`COUNTRY`, `REGION`, `CITY`, `UTM_SOURCE`, `UTM_MEDIUM`, `UTM_CAMPAIGN`, `PATH`,
`ENTRY_PAGE`, `EXIT_PAGE`, `TOP_PAGE`, `REFERRER`, `TOP_REFERRER`, `OUTBOUND_LINK`,
`CUSTOM_EVENTS`, `EVENT_NAME`, `USER`.

The REST API takes the same dimensions in lower case (`top_page`); over MCP either
spelling is accepted.

### Custom Events

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `list_events` | List raw tracked events | `event`, `channel`, `userId`, `filters`, `page`, `size`, `sort` (`desc` default, `asc`) |
| `get_event_stats` | Grouped event counts | `groupBy` (`event` default, `channel`, `user`), `channel` |
| `get_event_timeline` | Event counts over time | `interval`, `event` |
| `get_event_breakdown` | Break events down by dimension (`EVENT_NAME`, `USER`, `COUNTRY`, …) | `dimension` (required), `limit` |

### Users

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `list_users` | List/search aggregated user analytics | `type` (`all`/`identified`/`anonymous`), `search`, `filters`, `page`, `size` |
| `get_user_summary` | Comprehensive single-user summary | `userId` (required) |
| `get_user_activity` | Daily activity heatmap for one user | `userId` (required), `months` (default 4); no date params |
| `get_user_events` | Paginated event timeline for one user | `userId` (required), `page`, `size`; no date params |

### Sessions

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `list_sessions` | List aggregated sessions | `search`, `filters`, `page`, `size` |
| `get_session_detail` | Single session details (metadata only) | `sessionId` (required); no date params |
| `get_session_events` | Events inside one session | `sessionId` (required), `page`, `size`; no date params |

### Funnels & Journeys

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `analyze_funnel` | Ad-hoc funnel: conversion + drop-off per step | `steps` (required — ordered list of `{type, value, name?, filters?}`), `analysisMode` (`session`/`user`) |
| `analyze_journey` | Most common multi-step event sequences | `steps` (count, default 3), `limit` (default 100) |

### Frustration Signals

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `get_frustration_signals` | Rage clicks and dead clicks, with top pages/elements | `limit` |

### Retention

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `get_retention` | Cohort retention: visitors grouped by the week/month of their first visit, with the share still active in each following period | `interval` (`week` default, or `month`) |

Cohorts are anchored to each visitor's **first visit ever**, not the first visit inside the requested window, so long-standing visitors are never counted as new. Offset 0 is the cohort itself (100%). The date range selects which cohorts are returned.

### Realtime

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `get_realtime_visitors` | Distinct visitors active right now | `windowMinutes` (1–60, default 5); no date params |

### AI Visibility

How often your brand appears in AI search answers (ChatGPT, Gemini, Perplexity, Claude), which domains those answers cite, and how you stack up against competitors.

Most of these tools accept a `providers` filter — a list of platforms such as `["CHATGPT", "GEMINI"]`, where omitting it means every platform — and a `jobs` parameter, how many of the most recent scan jobs to aggregate when no date window is given (default 10). Six of them also take the [period comparison](#period-comparison) parameters, which need a date window rather than a `jobs` count.

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `list_ai_brands` | Configured brands (yours + competitors) | none |
| `list_ai_prompts` | Prompts tracked against AI platforms | none |
| `list_ai_topics` | Prompt topics (thematic groupings of prompts) | `includeArchived` (default false); no date params |
| `get_ai_visibility_series` | Visibility score over time | `providers`, `limit` (default 30) |
| `get_ai_visibility_domains` | Domains AI answers cite, ranked by citation share | `providers`, `jobs`, `limit` (default 25) |
| `get_ai_cited_pages` | The specific pages (URLs, with titles) AI answers cite, ranked by citation count | `providers`, `mentioningBrand`, `topicIds`, `jobs`, `limit` (default 25) |
| `get_ai_competitors` | Your brand vs competitors (mentions, sentiment) | `providers`, `jobs`, `limit` |
| `get_ai_share_of_voice` | Your share of all brand mentions over time | `providers`, `jobs` |
| `get_ai_prompts_breakdown` | Per-prompt: did the brand appear in each provider's answer | `jobs` |

### Bot & AI-Crawler Traffic

Which bots and AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Googlebot, …) hit your site, from where, and what they read.

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `get_bot_timeline` | Bot requests over time, grouped by vendor | `interval` |
| `get_bot_countries` | Per-country bot traffic (requests + distinct bots) | `page`, `size` (default 8) |
| `get_top_bots` | Top bots ranked by request count | `size` (default 10) |
| `get_bot_top_paths` | Pages most requested by bots | `size` (default 10), `vendor` (e.g. `GPTBot`) |

All four also take the [period comparison](#period-comparison) parameters, which is how "is ChatGPT crawling us more than last month?" gets answered in one call.

### Backlinks

Referring domains detected from the project's real traffic — search engines, social networks, AI assistants, and self-referrals are excluded. These tools use a `days` window instead of the standard date parameters.

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `list_backlinks` | Referring domains with referred-visit counts | `status` (`all` default, `active`, `ignored`, `lost`, `untapped`), `sort` (`first_seen` default, `sessions`), `q` (domain search), `days` (default 30), `page`, `size` |
| `get_backlink_detail` | One referring domain: daily visit timeline, landing pages, and the linking-page URLs | `domain` (required), `days` (default 30) |
| `get_backlink_reclamation` | Dead pages that still receive referral traffic — backlinks recoverable with a redirect | `days` (default 90) |
| `get_backlink_opportunities` | Domains AI answers cite where your brand is absent — sites worth earning a link from; requires AI Visibility to be configured | `jobs`, `limit` (default 25) |

### Content Recommendations

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `get_content_recommendations` | AI-generated create/update-page recommendations, each with the analytics, AI-visibility, and SERP facts it is grounded in | `status` (`SUGGESTED`/`ACCEPTED`/`DONE`/`DISMISSED`, default all), `page`, `size`; no date params |

### Workflow Reads

Workflows are the automations built on the dashboard's workflow canvas. These reads require `workflow.view`; the tools that change a workflow are under [Workflows](#workflows). None accept date parameters.

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `list_workflows` | The project's workflows with their status (`DRAFT`, `ACTIVE`, `PAUSED`, `ARCHIVED`); graphs omitted | `page`, `size` (default 20) |
| `get_workflow` | One workflow with its full graph — every step, its config, and the connections between them | `workflowId` (required) |
| `list_workflow_step_types` | The catalog of step types: what each does, the payload types its inputs accept and its outputs emit, whether it costs AI credits, and every config key it takes | none |
| `list_workflow_runs` | A workflow's runs, most recent first, with status, trigger, cost and any error | `workflowId` (required), `page`, `size` |
| `get_workflow_run` | One run in detail: every step's status, what arrived on its inputs, what it emitted, and why it failed or was skipped | `workflowId`, `runId` (required) |

### Site Audit Reads

Everything a [site audit](/site-audit) produced. All of them require `siteaudit.view`, and none accept date parameters.

Each report tool takes an optional `auditId` and falls back to the project's most recent audit **of its own website**, so an assistant that has just been told about an audit does not need a second call to name it. An audit can be pointed at any address, and a competitor's report is never what an unqualified question means — so reading one means naming its id, which `list_site_audits` returns. There is no living page inventory behind these — every answer comes from one run's snapshot, so two figures read together were measured by the same crawl.

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `list_site_audits` | Recent audits, most recent first | `limit` (default 10) |
| `get_site_audit_worklist` | The whole audit as one table to work through, worst first: every failed rule with why it matters, how to fix it, how many pages carry it, and the first few of those URLs. `list_site_audit_issues` plus the first page of `list_site_audit_issue_pages` for every rule, in one call — the place to start when the task is "fix what the audit found" | `auditId`, `limit` (default 20, max 100), `examplesPerIssue` (default 3, max 10) |
| `get_latest_site_audit` | The most recent audit of the project's **own** website: weighted AI-readiness score, the 16-item scorecard, headline crawl statistics | `includeExternal` (default false) |
| `get_site_audit` | One audit in full, by id: which site it ran against and whether that is your own, the score and its category scores, the scorecard's verdicts, which checks the run was narrowed to, headline statistics | `auditId` |
| `get_site_audit_summary` | One audit's headline statistics: pages crawled, issues by severity, average response time, and how many pages came back blocked, broken or erroring | `auditId` |
| `list_site_audit_issues` | What the audit found, one row per rule, worst first — why it matters, how to fix it, how many pages it affects | `auditId` |
| `list_site_audit_checks` | Every check the audit graded, worst first, **including the ones that hold up** — each with what this run measured, how to fix it, and the pages it names. The issue tools are issues-only, so this is the only way to tell "passed" from "never ran", and the only place that reports how many checks ran at all | `auditId` |
| `list_site_audit_performance` | Lighthouse measurements, one row per page and device: performance, accessibility, SEO and best-practices scores plus LCP, FCP, CLS, TBT, TTFB and Speed Index | `auditId`, `device`, `band`, `failuresOnly`, `sort`, `q`, `page`, `size` |
| `get_site_audit_performance_page` | One measurement with the audits it failed, worst first — what Lighthouse objected to (render-blocking resources, unsized images, long main-thread work), not just the score it ended on | `resultId` (required), `auditId` |
| `list_site_audit_duplicates` | Pages that say the same thing, clustered by meaning and tightest first. `NEAR_DUPLICATE` is two pages that are nearly the same page — the ones worth merging or canonicalising; `RELATED` is normal for a site about one subject | `auditId` |
| `list_site_audit_issue_pages` | The pages behind one issue. Pass **both** `source` and `findingId` exactly as `list_site_audit_issues` returned them — a rule id is only unique within its source | `source` and `findingId` (both required), `auditId`, `page`, `size` |
| `list_site_audit_crawled_pages` | The page-by-page snapshot of one audit's crawl: status, title, word count, images missing alt text, response time, crawl depth, issue count | `auditId`, `status`, `sort`, `q`, `page`, `size` |
| `list_site_pages` | The same page list for the project's **latest completed audit of its own website** — the shortcut for "what does our site consist of right now" | `page`, `size`, `sort`, `filter`, `q` |
| `get_site_audit_page` | Everything one audit knows about one page: what the crawl measured, which checks it failed and what each found, how a model read it, and the nearest pages by meaning. Address it by `url` or by the `pageId` from `list_site_audit_crawled_pages` | `url` **or** `pageId` (one required), `auditId` |
| `get_page_content` | The same page detail for the project's own site, addressed the way a person names it — by path | `path` (required), e.g. `/pricing` |

`sort` takes `URL`, `STATUS`, `SPEED`, `WORDS` or `DEPTH` (default `URL`). The status filter — `status` on `list_site_audit_crawled_pages`, `filter` on `list_site_pages` — takes `ALL`, `OK`, `REDIRECT`, `BROKEN`, `SERVER_ERROR`, `BLOCKED` or `MISSING` (default `ALL`). `q` is a case-insensitive substring match on the URL.

On `list_site_audit_performance`, `device` takes `ALL`, `MOBILE` or `DESKTOP`, `band` takes `ALL`, `GOOD`, `NEEDS_WORK` or `POOR`, and `sort` takes `PERFORMANCE`, `URL`, `LCP`, `CLS` or `TTFB` (default `PERFORMANCE`, worst first).

Two empty answers mean "did not run" rather than "nothing found": no Lighthouse rows means no measurement happened — no provider configured, or the audit predates it — not that the pages are fast, and `list_site_audit_duplicates` reporting `pagesCompared: 0` means the similarity pass never ran, not that no page repeats another.

::: warning A project with no finished audit has no pages
`list_site_pages` and `get_page_content` read stored rows only. If the project has never completed an audit of its own website there is nothing to read — start one with `start_site_audit` first. A path nobody crawled is reported as not found rather than as an empty page, because "we looked and there is nothing there" and "we never looked" are different answers.
:::

### Reviewing a Draft Before You Publish

Every tool above reads a crawl, so the earliest they can see an article is after it is live — and by then the expensive mistake is already quotable. `audit_draft` takes the file instead: your agent reads the draft off disk, passes the text, and gets back the checks the site audit runs on a published page, plus the one only a pre-publish review can make — whether the draft contradicts something your site already says.

| Tool | Description | Extra parameters |
|------|-------------|------------------|
| `audit_draft` | Review an unpublished article: the prose checks the page report runs, plus the figures, structure words and titles it would contradict on the live site | `content` (required), `format` (`markdown`/`html`, detected when omitted), `title`, `metaDescription`, `path`, `auditId` |

Requires `siteaudit.view`. Nothing is stored: the draft is read, graded and forgotten. The dashboard runs the same review on the same endpoint — Website Scan → [Review a draft](/site-audit#reviewing-an-article-before-it-is-published) — for the times nobody is at a terminal.

```
"Audit blog/ai-visibility.md before I publish it"
```

**Pass the text, not a path.** The server cannot read your disk — the client opens the file. Markdown front matter is read for `title` and `description`, so a normal blog file needs nothing else; `path` is worth passing when you know where the piece will live, because it enables the check against the page already at that address.

The response answers "publish or not" first and gives the reasons under it:

| Field | What it says |
|-------|--------------|
| `verdict` | `BLOCK` only when the draft **contradicts** the published site. A thin description or a missing opening answer is a fix, not a contradiction, and comes back `WARN`; `CLEAR` means nothing this review can see would be contradicted |
| `summary` | One line: contradictions, what to fix, what is worth a look, and how many checks hold up |
| `checks[]` | Every graded line — passes included — with `status` (`FAIL`/`WARNING`/`PASS`/`INFO`), what was measured, and what to do about it |
| `comparedSite` | The audit the draft was read against and how many pages that comparison saw. `null` when the project has no completed audit of its own site |
| `comparisonNote` | Why the comparison is missing or partial, when it is |
| `onlyAfterPublishing` | The checks this review deliberately does not answer |

**What it grades depends on what you send.** A markdown file is the prose you own, so it is graded on the opening answer, question headings, statistics, heading order, lists and tables, length, title, description and image alt text. Structured data, social tags and the byline belong to the template that renders it — asked only of an HTML draft, which is the whole page. Internal versus outbound links need to know which host is yours, so they are graded only when there is an audit supplying the domain.

::: warning A CLEAR draft is not a clean audit
`onlyAfterPublishing` exists because a file cannot answer everything: HTTP status, the canonical tag, sitemap membership, whether AI crawlers are allowed in, and whether anyone has cited the page are all properties of a live URL. Review the draft here, then audit the page once it ships.
:::

Without a completed audit of your own website the contradiction half cannot run — the prose checks still do, and `comparisonNote` says exactly that. `start_site_audit` fixes it.

### Configuration Reads

Unlike the analytics reads above, these expose org/project configuration, so each requires the same view permission its dashboard page enforces. None accept date parameters.

| Tool | Description | Permission | Extra parameters |
|------|-------------|------------|------------------|
| `list_projects` | All projects in the connected organization | `project.read` | none |
| `list_webhooks` | The organization's webhooks | `webhook.view` | `page`, `size` (default 50) |

## Management Tools

These tools change configuration — never analytics data. They work **only over an OAuth connection** (see [Authentication](#authentication)): each checks the listed permission on the signed-in user and fails without it; private-API-key calls are rejected.

### AI Visibility Setup & Runs

All of these require the `aivisibility.manage` permission.

| Tool | Description | Parameters |
|------|-------------|------------|
| `add_ai_brand` | Add a brand — your own (`isSelf: true`, only one allowed) or a competitor | `name` (required), `primaryDomain`, `isSelf`, `aliases`, `excludedTopicIds` |
| `add_ai_competitor` | Add a competitor brand — shorthand for `add_ai_brand` without `isSelf` | `name` (required), `primaryDomain`, `aliases`, `excludedTopicIds` |
| `update_ai_brand` | Edit a brand's name, domain, aliases or topic scope, or (de)activate it | `brandId`, `name` (required), `primaryDomain`, `active`, `aliases`, `excludedTopicIds` |
| `delete_ai_brand` | Delete a brand | `brandId` (required) |

**Scoping a competitor to certain topics.** `excludedTopicIds` takes topic ids from `list_ai_topics` and mutes that competitor for them: it is treated as absent from every answer on those topics, so they leave its visibility rate and its share of voice, and it drops out of the leaderboard and charts whenever results are filtered to one. Resolve the topic name to an id with `list_ai_topics` first, and read a brand's current scope from `list_ai_brands`.

The set is replaced wholesale, so send the full list. On `update_ai_brand`, **omitting the parameter leaves the current scope untouched** — unlike `aliases`, which clears when omitted — so editing a name can't wipe a scope set in the dashboard. Send an empty array to deliberately track the competitor everywhere again. It is rejected for your own brand.
| `add_ai_prompt` | Add a prompt tracked across answer platforms | `text` (required), `locale` (default `en-US`), `topicId`, `personaId` |
| `update_ai_prompt` | Edit a prompt's text or locale, or (de)activate it. It cannot change the topic or persona — use the two tools below | `promptId`, `text` (required), `locale`, `active` |
| `move_ai_prompts_to_topic` | File prompts under one topic, or take them out of every topic by omitting `topicId`. Pass one id to move one prompt; all or nothing across the list | `promptIds` (required, ≤500), `topicId` |
| `assign_ai_prompt_persona` | Assign one persona to prompts, or unassign them by omitting `personaId`. Never touches their topic or text | `promptIds` (required, ≤500), `personaId` |
| `delete_ai_prompt` | Deactivate (remove) a prompt | `promptId` (required) |
| `add_ai_topic` | Create a prompt topic (thematic grouping) | `name` (required) |
| `update_ai_topic` | Rename a topic | `topicId`, `name` (required) |
| `delete_ai_topic` | Archive a topic — its prompts become uncategorized; historical runs keep the topic | `topicId` (required) |
| `suggest_ai_prompts` | Generate prompt ideas for a brand — nothing is saved; pass the keepers to `add_ai_prompt` | `brandName` (required), `primaryDomain`, `count` (1–15, default 8) |
| `list_ai_exploration_engines` | The platforms Prompt Explorer can run right now. Call it before `explore_ai_prompt`: this list is **not** the tracked-analysis platform list, and anything outside it is rejected | none |
| `explore_ai_prompt` | Ask one question of up to 4 platforms at once and read every answer, the brands each named, and the sources it cited. **Spends the organization's AI budget on every call** — ask the user first, and don't loop over reworded variations: an identical question is free for 7 days, a reworded one is a fresh purchase, and a daily cap will start refusing calls. Nothing is tracked; use `add_ai_prompt` for a question worth monitoring | `promptText`, `providers` (required, 1–4), `highlightBrand`, `region` (`US`/`EU`), `analyze` (default true), `runFresh` |
| `pause_run`, `resume_run`, `cancel_run` | Control an in-flight analysis run | `jobId` (required) |

### Site, SEO & Content

| Tool | Description | Permission | Parameters |
|------|-------------|------------|------------|
| `start_site_audit` | Start a link-following crawl and technical/SEO/AI-readiness audit of the connected project's website | `siteaudit.manage` | `maxPages` (defaults to the service setting), `followLinks` (default true) |
| `update_backlink_status` | Set a backlink source to `active` (shown) or `ignored` (dismissed as noise) | `backlinks.manage` | `backlinkId`, `status` (required) |
| `update_recommendation_status` | Move a content recommendation to `ACCEPTED`, `DONE`, or `DISMISSED` | `contentrecs.manage` | `recommendationId`, `status` (required), `dismissedReason` |

`start_site_audit` always audits the connected project's own website, and runs every check the server can run. Auditing somebody else's site, or narrowing a run to a subset of the checks, is a [dashboard](/site-audit#running-an-audit) decision — an assistant cannot spend your daily allowance for audits of other websites on its own.

### Projects & Organization

| Tool | Description | Permission | Parameters |
|------|-------------|------------|------------|
| `create_project` | Create a project in the connected organization | `project.create` | `name`, `projectType` (required), `description`, `websiteDomain` |
| `update_project` | Update the project's name, description, or website domain | `project.update` | `name` (required), `description`, `websiteDomain` (empty string clears it) |
| `update_organization` | Organization settings: name, logo, 2FA requirement, data-retention notification emails | `organization.update` | `name`, `logoUrl`, `require2fa`, `dataRetentionNotificationsEnabled` (all optional) |

### Webhooks

Webhooks are organization-scoped, not per-project.

| Tool | Description | Permission | Parameters |
|------|-------------|------------|------------|
| `create_webhook` | Create a webhook that POSTs subscribed events to a URL | `webhook.create` | `name`, `url`, `events` (required), `secret`, `enabled` (default true) |
| `update_webhook` | Update name, URL, events, secret, or enabled state | `webhook.update` | `webhookId` (required); the rest optional — `events` replaces the whole set, empty `secret` clears it |
| `delete_webhook` | Delete a webhook | `webhook.delete` | `webhookId` (required) |

### Workflows

Everything the workflow canvas can do: author a graph, validate it, publish it, run it. Authoring requires `workflow.manage` and running requires `workflow.run` — the same permissions the dashboard enforces — and both are held to the plan's workflow entitlements (feature enabled, active-workflow cap, monthly run allowance, AI budget).

Start with [`list_workflow_step_types`](#workflow-reads): it returns each step type's ports (which decide what can connect to what) and its config keys, so a graph can be built without guessing. Every authoring tool returns the workflow with its updated graph.

| Tool | Description | Permission | Parameters |
|------|-------------|------------|------------|
| `create_workflow` | Create a workflow, empty or with its steps and connections in one call. It starts as a `DRAFT` | `workflow.manage` | `name` (required), `description`, `steps` (`{type, key?, config?}`), `connections` (`{fromKey, toKey, fromHandle?, toHandle?}`) |
| `update_workflow` | Rename a workflow or change its description; omitted fields are left alone | `workflow.manage` | `workflowId` (required), `name`, `description` |
| `duplicate_workflow` | Copy a workflow's steps, connections and settings into a new `DRAFT` | `workflow.manage` | `workflowId` (required), `name` (defaults to `"<name> (copy)"`) |
| `delete_workflow` | Delete a workflow and its run history; can report that it is pending schedule teardown — retry shortly | `workflow.manage` | `workflowId` (required) |
| `add_workflow_step` | Add a step, optionally wiring it to an existing one in the same call | `workflow.manage` | `workflowId`, `type` (required), `config`, `key` (defaults to the lowercased type), `afterKey` |
| `update_workflow_step` | Change a step's settings; the given keys are merged into its config, and a null clears one | `workflow.manage` | `workflowId`, `stepKey`, `config` (required) |
| `remove_workflow_step` | Remove a step and every connection that touched it | `workflow.manage` | `workflowId`, `stepKey` (required) |
| `connect_workflow_steps` | Feed one step's output into another's input | `workflow.manage` | `workflowId`, `fromKey`, `toKey` (required), `fromHandle` (default `out`), `toHandle` (default `in`) |
| `disconnect_workflow_steps` | Remove the connection(s) between two steps, leaving both in place | `workflow.manage` | `workflowId`, `fromKey`, `toKey` (required) |
| `set_workflow_graph` | Replace the whole graph — for rebuilding rather than editing. Anything not listed is dropped | `workflow.manage` | `workflowId`, `steps` (required), `connections` |
| `validate_workflow` | Check whether the draft could be published; returns each error pinned to a step or a connection | `workflow.manage` | `workflowId` (required) |
| `publish_workflow` | Compile the draft, make it the live version, and start its schedule. Fails with the validation errors if it is not runnable | `workflow.manage` | `workflowId` (required) |
| `unpublish_workflow` | Retire the live version, stop the schedule, and return the workflow to `DRAFT` | `workflow.manage` | `workflowId` (required) |
| `run_workflow` | Start a run and return its id; runs are asynchronous, so poll `get_workflow_run` | `workflow.run` | `workflowId` (required), `mode` (`PUBLISHED` default, or `DRAFT_TEST`), `upToStepKey` (runs only that step and everything feeding it) |
| `cancel_workflow_run` | Cancel a run that is still in flight | `workflow.run` | `workflowId`, `runId` (required) |

A worked example — a weekly check of the site's busiest pages, emailed out:

```
list_workflow_step_types                              → what steps exist and what they accept
create_workflow  name: "Weekly page health"
add_workflow_step  type: SCHEDULE_TRIGGER   config: {"frequency": "WEEKLY"}
add_workflow_step  type: MY_SITE_PAGES      config: {"source": "TOP_TRAFFIC", "limit": 10}
                   afterKey: schedule_trigger
add_workflow_step  type: PAGE_HEALTH_CHECK  afterKey: my_site_pages
add_workflow_step  type: EMAIL_DELIVER      config: {"recipients": ["you@company.com"]}
                   afterKey: page_health_check
validate_workflow                                     → fix anything it reports
publish_workflow                                      → live, and running every week
```

### Team

| Tool | Description | Permission | Parameters |
|------|-------------|------------|------------|
| `invite_member` | Invite a user to the organization by email, with a role | `member.invite` | `email`, `roleId` (required) |
| `cancel_invitation` | Cancel a pending invitation | `invitation.cancel` | `invitationId` (required) |
| `change_member_role` | Change a member's role | `member.update_role` | `memberId`, `roleId` (required) |
| `remove_member` | Remove a member from the organization | `member.remove` | `memberId` (required) |

## Common Parameters

### Date Filtering

Most tools accept date filtering via either a preset or an explicit date range:

* **`preset`** — one of `last_30_minutes`, `last_hour`, `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_month`, `this_year`
* **`from`** / **`to`** — explicit date range in `YYYY-MM-DD` format (inclusive)

If both a preset and explicit dates are provided, **the preset takes precedence**.

Every window is resolved on the server in the project's [reporting timezone](/web-analytics#reporting-timezone) — the same way the dashboard resolves it. That is why a relative period should be asked for with its preset rather than with dates the assistant computes: the dashboard's *Last 7 days* is `last_7_days` (today plus the six days before it), and an assistant that sends `from = today − 7, to = today` instead reads one day more and reports different numbers for the same funnel. Reserve `from`/`to` for explicit calendar dates. `analyze_funnel` echoes the days it actually covered as `from`/`to` in its response, so the period an assistant quotes is the one the numbers came from.

For the AI visibility tools, omitting all date parameters aggregates the last `jobs` scan jobs instead of a time window.

### Period comparison

Thirteen of the read tools answer for an earlier window in the same call, so an assistant can say what changed without running the query twice and subtracting. They do it by default; these parameters change which window:

* **`comparePreset`** — one of `previous_period`, `previous_week`, `previous_month`, `previous_quarter`, `previous_year`
* **`compareFrom`** / **`compareTo`** — a custom comparison window in `YYYY-MM-DD` format (inclusive); send both or neither

`comparePreset` takes precedence when both are given, and omitting all three compares against the previous period — an assistant gets the change for free and only names a parameter to ask for a different window. `previous_period` keeps the length of your window and ends where it starts; the calendar presets are instead the week, month, quarter or year running up to it, which are usually longer — so an assistant comparing a day against `previous_month` is comparing it with the month behind it, not with the same day a month ago. [Compare to an earlier period](/web-analytics#compare-periods) has the full semantics, the one-year guard, and how the extra fields read.

| Area | Tools |
|---|---|
| **Web analytics** | `get_web_summary`, `get_web_timeline`, `get_web_breakdown` |
| **Bots & crawlers** | `get_bot_timeline`, `get_bot_countries`, `get_top_bots`, `get_bot_top_paths` |
| **AI visibility** | `get_ai_visibility_series`, `get_ai_visibility_domains`, `get_ai_cited_pages`, `get_ai_competitors`, `get_ai_share_of_voice`, `get_ai_prompts_breakdown` |

::: warning AI visibility comparisons need a date window
The AI visibility tools fall back to aggregating the last `jobs` scans when no dates are given — a count, not a period. A comparison asked for in that mode is refused rather than silently dropped, so pass `preset` or `from`/`to` alongside it.
:::

### Pagination

List tools support pagination with **`page`** (0-indexed) and **`size`**.

### Filters

Web analytics and event tools support filters in the format `dimension:operator:values`:

```
"country:is:US,UK"
"browser:is:Chrome"
"page:contains:/blog"
```

Pass multiple filters as an array to combine them.

## Example Prompts

| Question | Tools Used |
|----------|------------|
| "How many visitors are on the site right now?" | `get_realtime_visitors` |
| "How many visitors did we get last week?" | `get_web_summary` |
| "Compare this week's traffic to last week by country" | `get_web_breakdown` with `comparePreset` |
| "What's our weekly retention looking like this quarter?" | `get_retention` |
| "Show me the signup funnel conversion rate" | `analyze_funnel` |
| "How visible is our brand in AI search this month?" | `get_ai_visibility_series` |
| "Which domains does ChatGPT cite instead of us?" | `get_ai_visibility_domains` |
| "What are the most cited pages for our lead-capture topic?" | `get_ai_cited_pages` |
| "How do we compare to competitors in AI answers?" | `get_ai_competitors` |
| "Is ChatGPT crawling our docs? Which pages?" | `get_top_bots` + `get_bot_top_paths` |
| "Which pages have the most rage clicks this week?" | `get_frustration_signals` |
| "Show me a summary of user U-123's activity" | `get_user_summary` |
| "Add Vercel as a competitor we track in AI answers" | `add_ai_competitor` |
| "Stop counting Blinq on the badge-scanning topic" | `list_ai_topics` + `list_ai_brands` + `update_ai_brand` |
| "Suggest prompts for my brand and track the good ones" | `suggest_ai_prompts` + `add_ai_prompt` |
| "What does AI say about us right now?" | `list_ai_exploration_engines` + `explore_ai_prompt` |
| "Run a site audit and walk me through the findings" | `start_site_audit` + `get_latest_site_audit` + `list_site_audit_issues` |
| "Fix everything the last audit found, in my codebase" | `get_site_audit_worklist` + `list_site_audit_issue_pages` |
| "Which pages are slowest, and what is slowing them down?" | `list_site_audit_performance` + `get_site_audit_performance_page` |
| "What's wrong with our pricing page?" | `get_page_content` |
| "Check this draft before I publish it" | `audit_draft` |
| "Which sites should we try to get links from?" | `get_backlink_opportunities` |

## Connect external MCP servers to the assistant

The direction above is Kitbase acting as an MCP server. The project assistant
can also act as an MCP **client**: connect any Streamable HTTP MCP server and
its tools become available to the assistant in chat.

**Where:** Project Settings → Assistant → Connect server.

| Field | Rules |
|---|---|
| Name | 2–24 chars, lowercase letters/digits/hyphens. Immutable — it namespaces the server's tools as `mcp__<name>__<tool>`. |
| URL | The server's Streamable HTTP endpoint. `https` only. |
| Authentication | **Auth header** or **OAuth**, chosen at creation and immutable afterwards. |
| Auth header | Header connections only. Either a full `Name: value` line, or a bare token sent as `Authorization: Bearer <token>`. Stored encrypted; write-only — it can be replaced or removed, never read back. |
| Require approval | On by default: every tool call from this server pauses the chat for your approval, showing the exact arguments. Turn it off only for servers you trust. |

### OAuth-protected servers

Servers that authenticate with OAuth — Atlassian's
`https://mcp.atlassian.com/v1/mcp/authv2`, for example — need no token pasted
in. Create the connection with **OAuth**, then press **Connect**: Kitbase asks
the server who authorizes it, registers itself as a client, and sends you to
that server's own consent screen. Approve there and you land back on the
project's settings page with the connection live.

* The grant belongs to the account you approved it with, and Kitbase keeps it
  alive by refreshing it in the background. Tokens are encrypted at rest and
  are never shown, exported, or returned by the API.
* Until you complete the flow, an OAuth connection holds no credential and
  contributes no tools.
* If the server revokes the grant — or you remove Kitbase's access on its
  side — its tools stop appearing. Press **Connect** again to re-authorize.
* Servers that do not offer dynamic client registration cannot be connected
  this way; use an auth header instead.

Behavior and limits:

* Up to 10 connections per project; the first 40 tools per server are offered.
* Tool lists refresh about once a minute; an unreachable server simply
  contributes no tools until it answers again. Use **Test** to dial a
  connection on demand and list its tools.
* External results are treated as untrusted data by the assistant — a page or
  tool output cannot instruct it to change its behavior.
* Connections are project-scoped, changes are audit-logged, and creating or
  editing them requires the `project.update` permission.

## Requirements

* A Kitbase account with an active project
* An MCP-compatible client that supports remote servers over Streamable HTTP
* For API-key auth: a private API key (`sk_kitbase_`) from **Project Settings > API Keys**

## Next steps

* [Project Assistant](/guide/assistant) — the same tools, built into the dashboard, with no client to connect.
* [CLI](/cli) — the same operations from your terminal instead of an AI assistant, and where `kitbase login` lives.
* [API reference](/api-reference) — the REST API behind every MCP tool.
* [Analytics dashboard guide](/guide/analytics) — the data these tools query.

---

---
url: 'https://docs.kitbase.dev/cli.md'
description: >-
  The Kitbase CLI — manage webhooks, projects, and analytics from your terminal
  or CI. Browser-based login, API-key auth, and JSON output for scripting.
---

# CLI

The Kitbase CLI (`@kitbase/cli`) lets you do anything the [dashboard](https://app.kitbase.dev) can do, from your terminal — webhooks, projects, analytics, billing, and more, with `--json` output for scripting and CI.

## Installation

::: code-group

```bash [pnpm]
pnpm add -g @kitbase/cli
```

```bash [npm]
npm install -g @kitbase/cli
```

```bash [npx]
npx @kitbase/cli login
```

:::

## Quick start

```bash
# Log in via your browser (no password typed in the terminal)
kitbase login

# Pick a default organization and project so you don't have to pass --org/--project every time
kitbase use org
kitbase use project

# Now run any command
kitbase events list
kitbase webhooks list --json | jq
```

## Authentication

### Browser login (interactive use)

`kitbase login` works like the GitHub CLI: it prints a short code and opens `https://app.kitbase.dev/cli/authorize?session=...` in your browser. Confirm the code on the page matches the one in your terminal, approve, and the CLI picks up the session automatically — instantly via a local loopback ping, or within a few seconds via polling, so it also works over SSH and on headless machines.

::: warning Never approve a login you didn't start yourself.
:::

Credentials are stored in `~/.config/kitbase/credentials.json` (mode `0600`), one entry per API base URL. The access token refreshes automatically in the background; the underlying session lasts 60 days. Run `kitbase logout` to revoke it server-side and clear the local credential.

**A CLI session is exactly as strong as the browser session that approved it.** If your organization requires two-factor authentication, approve the login from a browser session that actually used a second factor — a password-only session produces a CLI token that the organization will refuse. Signing in to the dashboard with your second factor (or with a passkey) before approving is enough.

::: tip Refreshing happens automatically — don't do it yourself.
A refresh token is single-use. If two processes present the same one, Kitbase treats it as a stolen credential and revokes every session for your account, which logs out your other machines too. Running the CLI concurrently is fine; sharing one `credentials.json` between machines is not.
:::

### Private API key (CI/CD)

Create a secret key in the dashboard (**Project Settings → API Keys**, `sk_kitbase_...`), then either export it or pass it per command:

```bash
export KITBASE_API_KEY=sk_kitbase_...
kitbase webhooks list

# or
kitbase webhooks list --api-key sk_kitbase_...
```

A key resolves its own organization and project automatically — no need to run `use org` / `use project` first.

## Organization & project context

Most commands operate on a project inside an organization. Resolution order, per command:

1. `--org` / `--project` flags
2. `KITBASE_ORG` / `KITBASE_PROJECT` environment variables
3. The default set via `kitbase use org` / `kitbase use project`
4. (API-key auth only) resolved automatically from the key itself
5. An interactive picker, if you're in a terminal
6. Otherwise, a clear error telling you what to run

Run `kitbase context` at any time to see the current base URL, auth mode, org, and project.

## Output

Every command prints a human-readable table or key/value view by default. Pass `--json` for machine-readable output:

```bash
kitbase webhooks list --json | jq '.data[].url'
```

## Request bodies

Simple fields are individual flags (`--name`, `--enabled`, ...). For anything with nested objects or arrays, use `--data` — it accepts a literal JSON string, `@file.json`, or `-` for stdin:

```bash
kitbase webhooks create --data '{"name": "Deploy hook", "url": "https://example.com/hooks/kitbase", "events": ["project_created"]}'
echo '{"name": "Deploy hook", ...}' | kitbase webhooks create --data -
kitbase webhooks create --data @webhook.json
```

Individual flags always take precedence over matching keys in `--data`.

## Self-hosted backends

```bash
kitbase webhooks list --local          # shorthand for --base-url http://localhost:8100/api
kitbase webhooks list --base-url https://api.your-domain.com
```

## Commands

`kitbase --help` lists every topic. The session and context commands:

| Command | Description |
| --- | --- |
| `login` | Log in via your browser |
| `logout` | Log out and revoke the session server-side |
| `whoami` | Show the currently logged-in user (or API key context) |
| `use org [slug]` | Set the default organization (interactive picker if omitted) |
| `use project [id]` | Set the default project (interactive picker if omitted) |
| `context` | Show the current base URL, auth mode, org, and project |

Everything else — `webhooks`, `projects`, `ai-visibility`, `backlinks`, `billing`, `events`, `funnels`, `integrations`, `sdk-keys`, `private-api-keys`, `organizations`, `members`, `invitations`, `notifications`, `sessions`, `web-analytics`, and more — is generated from a curated, CLI-scoped subset of the Kitbase API's OpenAPI spec, one command per operation, grouped into topics matching the [API's resource structure](/api-reference). Run `kitbase <topic> --help` to see what's available under it.

## Next steps

* [API reference](/api-reference) — the REST API behind every CLI command.
* [MCP Server](/sdks/mcp) — query the same data from AI assistants instead of the terminal.
* [SDKs & Tools](/sdks/) — all official SDKs and integrations.

---

---
url: 'https://docs.kitbase.dev/guide.md'
description: >-
  Learn the Kitbase dashboard — the project assistant, analytics metrics and
  breakdowns, the events view, session analytics, and user profiles with
  identity resolution.
---

# Dashboard Guide

The assistant is where a project opens: ask a question, get an answer read straight from your data. The four views below are where you go when you want to explore rather than ask.

## How the views connect

* **[Assistant](/guide/assistant)** sits on top of all of them: it reads the same data in plain language, and can change things with your approval.
* **[Analytics](/guide/analytics)** is the top-level picture: pageviews, visitors, sessions, and custom events over time, with breakdowns by page, referrer, device, browser, OS, country, and UTM parameters.
* **[Events](/guide/events)** is the raw feed underneath — every autocaptured and custom event, filterable by channel, tags, and enriched fields.
* **[Sessions](/guide/sessions)** groups events into visits: entry/exit pages, duration, and bounce rate.
* **[Users](/guide/users)** groups sessions into people: anonymous visitors become identified users via [identify()](/identify-users), with identity resolution stitching their history together.

## Next steps

* [Project Assistant](/guide/assistant) — ask about any of this in plain language.
* [Web Analytics overview](/web-analytics) — how data gets captured and enriched before it reaches the dashboard.
* [Track Events](/track-events) — add the custom events these views analyze.
* [Bot & Crawler Detection](/crawler-detection) — the separate dashboard for bot traffic.

---

---
url: 'https://docs.kitbase.dev/guide/assistant.md'
description: >-
  Ask questions about your project in plain language and act on the answers. The
  Kitbase assistant reads your analytics, AI visibility, backlinks, and site
  audits, and can make changes with your approval.
---

# Project Assistant

The assistant is the first thing you see when you open a project. Ask it anything about that project in plain language — it reads your data with the same tools the [MCP server](/sdks/mcp) exposes, and it can make changes when you ask it to.

It replaces the old overview dashboard. That dashboard answered a fixed set of questions well and everything else not at all; the assistant answers whatever you ask, and can act on the answer.

## What it can see

The assistant is scoped to one project and reads only that project's data:

| Area | Examples |
| --- | --- |
| Web analytics | Visitors, pageviews, sessions, bounce rate, breakdowns by page/referrer/country/device, period comparisons, retention, realtime |
| Events | Custom event stats, timelines, and breakdowns |
| Users & sessions | User profiles and activity, session detail and event streams, frustration signals |
| Funnels & journeys | Funnel conversion analysis, path analysis |
| AI visibility | Presence over time, share of voice, competitors, prompts, topics, cited domains |
| Bots & crawlers | Top bots, timelines, countries, most-crawled paths |
| Backlinks | Detected links, opportunities, reclamation candidates |
| Site audit | Latest and historical audits, their issues, and every page a crawl reached |
| Content recommendations | Open recommendations and their status |
| Webhooks | Configured webhooks and their events |

Some questions to start with:

* *"How did traffic change last week compared to the week before?"*
* *"Which pages lost AI visibility this month?"*
* *"Which of my pages have the worst audit scores?"*
* *"Which competitors are cited more than us, and on which prompts?"*

## What it can do

The assistant can also change things — add an AI-visibility brand, prompt, or topic; start a site audit; update a backlink or recommendation status; create or update a webhook.

**It can never do more than you can.** Every action is checked against your own permissions at the moment it runs, so a viewer asking the assistant to delete a brand gets the same refusal they would get from the UI.

Team and organization management — inviting or removing members, changing roles, editing organization settings — is deliberately outside its reach, along with creating projects. Those stay where you have to navigate to them on purpose.

### Actions that need your approval

Anything that removes data or breaks collection stops and asks first:

* Deleting an AI-visibility brand, prompt, or topic
* Deleting a webhook
* Cancelling a run
* Changing project settings, including the tracked domain

You see exactly what the assistant is about to do — the real arguments, not a paraphrase — and choose **Approve** or **Decline**. Declining is not a dead end: the assistant is told you said no and can suggest something else.

Everything else runs without interrupting you: reads are always safe, and creates and updates are recoverable.

## Attaching files

Attach a file with the paperclip, by dragging it onto the composer, or by pasting a screenshot straight in.

| Type | Limit |
| --- | --- |
| Images (PNG, JPEG, GIF, WebP) | 5 MB each |
| PDF | 10 MB each |
| Text, CSV, JSON, Markdown | 10 MB each |

Up to four files per message.

::: warning Attachments are not stored
A file is sent to the model for that one message and then discarded — only a note that you attached it is kept in the conversation. A later question cannot re-examine an earlier attachment, so attach it again if you need to ask about it a second time.
:::

## Conversations

Each conversation is private to you. Two people looking at the same project have their own separate histories.

* **New conversation** starts a fresh one and archives the current thread.
* **Conversations** opens your past threads, titled by their opening message.

Conversations survive a reload — including one paused on an approval prompt, which is still waiting when you come back.

A very long conversation eventually loses its beginning: the assistant reads back dozens of exchanges, but not forever, and the detail of what a lookup returned fades before the questions do. Ask it to remember anything that should outlast the thread — a remembered fact comes back on every future question about the project, here and in [Slack](/slack-assistant) alike.

## Cost

Assistant usage is metered per project and counts toward your AI spend, the same as [AI visibility](/ai-visibility) runs. Reads are cheap; the cost is dominated by how much data a question pulls in.

## Availability

The assistant needs an Anthropic API key configured on the server. On Kitbase Cloud it is always available. If you are self-hosting, set `ANTHROPIC_API_KEY` in the server environment — without it the composer explains that the assistant is not configured and the rest of the dashboard is unaffected.

## Next steps

* [Assistant in Slack](/slack-assistant) — the same assistant, from a DM or a channel.
* [Dashboard Guide](/guide/) — the other views in the dashboard.
* [MCP Server](/sdks/mcp) — the same tools, from Claude or any other MCP client.
* [AI Visibility](/ai-visibility) — the brand-mention data the assistant reads.
* [Analytics](/guide/analytics) — how the metrics it quotes are computed.

---

---
url: 'https://docs.kitbase.dev/slack-assistant.md'
description: >-
  Ask the Kitbase assistant about your analytics in plain language, from Slack.
  Set it up in about 30 seconds — no technical knowledge needed.
---

# Assistant in Slack

Ask Kitbase questions in plain language, in the channel where your team is
already talking. "How did the pricing page do last week?" "Which posts are
getting cited by ChatGPT?" "Why did signups drop on Tuesday?" You get the answer
in Slack, so nobody has to open a dashboard, find the right chart and paste a
screenshot back into the conversation.

It is the same [assistant](/guide/assistant) that lives in the Kitbase
dashboard — same data, same abilities. Slack is just a second place to reach it.

## Two ways to talk to it

* **Send it a direct message.** Open a DM with the Kitbase app and type. This is
  one running conversation, so you can follow up — "and the week before?" — without
  repeating yourself.
* **Mention it in a channel.** Type `@Kitbase` at the start of a message in any
  channel it has been invited to. It replies in a thread under your message, so
  two people can ask about different things in the same channel without the
  answers getting tangled.

It only speaks when spoken to. In a channel it never sees a message that does not
mention it.

::: info It can never do more than you can
Every answer runs as *your* Kitbase account, checked against your own permissions
at the moment you ask. If you cannot delete something in the dashboard, you
cannot get the assistant to delete it for you in Slack either.
:::

## Setting it up

### If you are the admin: connect Slack once

In Kitbase, go to **Organization → Integrations** and connect Slack. Slack will
ask you to approve the Kitbase app for your workspace. Approve it within 5
minutes of pressing connect — after that the link expires and you start again
from the same button.

If your organization already uses Slack for
[notifications](/guide/events), you are most of the way there — but see the
warning below.

In each channel, type `/invite @Kitbase`. The bot cannot see — or answer in — a
channel it has not been invited to.

Type `/kitbase` in the channel and follow the button. See
[Pointing a channel at a project](#pointing-a-channel-at-a-project) below.

::: warning Connected Slack before the assistant existed? Reconnect it.
An older connection was never given permission to *receive* messages, so the bot
will post notifications perfectly well and simply never answer anyone. Nothing
about that is visible from inside Slack, so Kitbase flags the integration as
needing a reconnect and refuses to connect accounts or channels against it,
rather than letting them quietly go nowhere.

Reconnecting is the same connect button, walked again. It updates the connection
you already have, so everyone's connected accounts and every channel's project
survive it. **Deleting the integration and starting fresh does not** — that takes
both with it. Notifications keep working either way.
:::

### If you are everyone else: about 30 seconds

Mention `@Kitbase` in a channel, or send it a direct message. Anything will do.

The bot replies with a message **only you can see**, holding a **🔑 Connect
Kitbase** button. It opens Kitbase in your browser.

The button works once and expires after 10 minutes. If you lose it or it goes
stale, just ask the bot again — every ask hands you a fresh one.

The page shows which Kitbase account you are signed in as, and what you are
agreeing to. If that is the wrong account, use **Not you? Use a different
account**. Then press **Connect**.

When you tapped the button from a channel, one more step follows: choose which
project that channel should talk about. Whatever the channel is already pointed
at comes preselected, so most people just press **Connect channel**.

Started in a DM instead? There is no page for this — the bot asks you right in
the chat with a project menu the first time you ask it something.

That is it. Ask your question again — the one that started all this was not kept.

You connect your account **once per Slack workspace**, not once per channel.

## Pointing a channel at a project

Every answer is about one Kitbase project, so each conversation has to be
pointed at one.

Type **`/kitbase`** anywhere, any time, to set or change it:

* **In a channel**, you get a private **🔑 Choose project** button that opens the
  same short Kitbase page. This works even in channels the bot has never been
  invited to.
* **In a DM with the bot**, the project menu appears right there in the chat. Pick
  one and you are done.

When a channel's project changes, the bot says so in the channel — *"Talking about
**Marketing site** here from now on."* — so nobody is left reading numbers for a
project they did not expect.

::: tip A channel is shared, a DM is yours
Changing what a **channel** talks about changes it for everyone in the room, so it
needs permission to manage the organization's integrations — normally an admin. If
you do not have it, Kitbase says your account is connected and to ask an admin.

Changing what your own **DM** talks about needs no permission at all. Any member
can do it.
:::

Admins can also see and change every channel's project from **Organization →
Integrations**, without going near Slack.

## Approving actions

Most of what the assistant does is read-only and simply happens. Anything that
would change or delete something — removing a brand, prompt, topic or webhook,
cancelling a run, renaming a project — stops and asks first:

> **Update project**
>
> ```
> {"name":"Docs site"}
> ```
>
> `Approve` `Deny`

Worth knowing:

* **Only the person who asked can answer it.** In a channel the buttons sit in
  front of everybody, but the action would run as *your* account, with your
  permissions and your name on it — so a colleague pressing *Approve* is refused.
* **It waits for all of them.** If the assistant wants to do two things, both get a
  prompt and nothing runs until both are answered.
* **Denying is a real answer.** The assistant is told you said no and carries on
  from there, usually by suggesting something else.
* **Once decided, the buttons disappear**, so nothing can run twice.
* **It waits as long as you need.** You can approve something the next morning. The
  request survives restarts and updates. After a week it expires and you ask again.

While a question like this is unanswered, the assistant will not take a new
message in that conversation — answer it and it carries on.

## What the answers look like

The answer arrives a piece at a time, in one message that grows as it is written,
the way it does in the dashboard. Tables, headings, lists and code all render as
Slack markdown.

Along the way you also see what it is doing. Each step the assistant takes —
reading an audit, looking up keywords, starting a crawl — appears as its own card
that turns from running to done, or to failed, with a line about what came of it.
The cards stay under the answer, so a report that took six steps still shows all
six. They are collapsed by default; open them when you want to check the working.

If something goes wrong — a rate limit, a spend cap, a step that failed — it says
so in the same message, along with whatever it did manage.

Under a finished answer are **Helpful** and **Not helpful** buttons. Pressing one
records what you thought of that answer, which is how we find the questions the
assistant is answering badly. Nothing else happens: it does not reply, retry, or
tell the channel.

### Files

Ask for something to keep — "write up last week's site audit as a PDF", "give me
those numbers as a CSV" — and the assistant writes the file and uploads it into
the conversation. It can produce PDF, Markdown, CSV and plain text.

Workspaces connected before file support existed were never given permission to
upload, so the assistant posts a link to the file in your dashboard instead.
Reconnect Slack from **Organization → Integrations** to get files in the thread.

## Disconnecting

Disconnecting is your own decision and needs no admin.

1. In Kitbase, click your avatar (top right) and choose **Settings**. You land on
   your **Profile** page.
2. Find the **Connected chats** card. Each row is one chat account that can speak
   for you — it shows your Slack name, the workspace, the organization it answers
   for, and when it was connected.
3. Press the trash icon on the row and confirm **Disconnect this chat account?**

The effect is immediate: the assistant stops answering as you everywhere in that
workspace. Nothing else changes — the channels your team set up keep their
projects, and everyone else's connections keep working.

To connect again later, just talk to the bot as if for the first time: it hands
you a fresh **🔑 Connect Kitbase** button. That is also how you move your Slack
account to a different Kitbase account or organization — disconnect, then connect
again with the other choice.

::: info Disconnecting yourself is not removing Kitbase from Slack
This only unhooks *your* account. Removing the app from the whole workspace is an
admin action, under **Organization → Integrations**.
:::

## What it will not do

* **It does not read your channels.** Only the messages that mention it, and the
  DMs you send it.
* **Editing a message changes nothing.** Fixing a typo does not re-ask the
  question — post a new message.
* **It cannot open files you attach in Slack.** Use the dashboard assistant for
  those.
* **It answers one question at a time per conversation.** A second message while it
  is still working gets a private "one moment" rather than a second answer.
* **It does not carry context between places.** A DM and a channel thread are
  separate conversations.
* **A very long conversation eventually loses its beginning.** It reads back a
  long way — dozens of exchanges — but not forever, and the detail of what a
  lookup returned fades before the questions do. If something matters beyond the
  conversation, ask it to remember that: a remembered fact comes back on every
  future question about the project, in Slack and in the dashboard alike.

## Slack app configuration

::: info For self-hosters
Kitbase Cloud users can skip this — the Slack app is already configured. This is
only for teams running their own Kitbase and their own Slack app.
:::

Point your Slack app at your Kitbase API. All three URLs use the same base as
`SLACK_REDIRECT_URI` in your [configuration](/self-hosting#slack):

| Slack app setting | Request URL |
| --- | --- |
| Event Subscriptions | `https://your-kitbase-domain/api/integrations/slack/events` |
| Interactivity & Shortcuts | `https://your-kitbase-domain/api/integrations/slack/interactivity` |
| Slash Commands → `/kitbase` | `https://your-kitbase-domain/api/integrations/slack/commands` |

Create the slash command as `/kitbase` — for example with the description "Choose
which Kitbase project this conversation is about".

The app needs these bot token scopes:

| Scope | Why |
| --- | --- |
| `app_mentions:read` | See messages that mention the app in a channel |
| `im:history` | See direct messages sent to the app |
| `chat:write` | Post, stream and edit its answers |
| `users:read` | Show who approved an action, by name |
| `channels:read`, `channels:join`, `groups:read` | Post notifications into channels |
| `commands` | Offer the `/kitbase` slash command |
| `files:write` | Upload files into the conversation (optional — without it, a file becomes a dashboard link) |

::: warning Adding `commands` needs a reinstall
Slack grants scopes once, when a workspace installs the app. A workspace that was
installed before `commands` was added will not show `/kitbase` until it
reauthorizes — reconnect Slack from **Organization → Integrations**.
:::

## Frequently asked questions

## Next steps

* [Assistant](/guide/assistant) — the same assistant in the dashboard, and everything it can do.
* [MCP Server](/sdks/mcp) — the same tools, from Claude or any other MCP client.
* [Events & notifications](/guide/events) — the other half of the Slack integration.

---

---
url: 'https://docs.kitbase.dev/guide/analytics.md'
description: >-
  Understand the Kitbase Analytics dashboard and how to use it to track page
  views, sessions, users, and custom events.
---

# Analytics

Kitbase provides privacy-friendly web analytics without cookies. Track page views, sessions, users, and custom events from a unified dashboard.

## Overview

Once you have the Kitbase SDK installed and initialized, analytics data flows into a single dashboard where you can monitor traffic, engagement, and conversions in real time. There are no cookies involved -- Kitbase relies on localStorage for anonymous identification and server-side enrichment for device, browser, and location data.

::: tip Guided setup in the dashboard
The first time you open the **Analytics** page in the dashboard, a setup wizard walks you through the whole flow — creating an SDK key, adding the tracking snippet for your stack (script tag, npm, React, or Angular), and live-verifying that the first pageview arrives.
:::

### Connect a website (optional)

When you create a project you can optionally connect a **public website domain** — or add one later on the project's **Website** page (under **Project** in the sidebar). Connecting a domain unlocks the site-facing features ([site audits](/site-audit), AI visibility); the Website page then shows the live status of every connection (tracking script, crawler forwarder, brand & prompts, site audit) and lets you run an audit from there. Projects that track an app or internal dashboard can skip this entirely — analytics, sessions, funnels, and journeys work without a website.

Once the script is verified and a website is connected, the analytics Overview shows a dismissible **get-started checklist** for the remaining areas (run your first audit, track AI answers, watch AI crawlers) until each has data.

## Dashboard Metrics

The analytics dashboard surfaces six core metrics at a glance:

| Metric | Description |
|--------|-------------|
| **Total Events** | The total number of events received in the selected time range |
| **Unique Users** | Distinct anonymous or identified users who triggered at least one event |
| **Sessions** | Total user sessions (a session ends after 30 minutes of inactivity) |
| **Page Views** | Total `screen_view` events recorded |
| **Bounce Rate** | Percentage of single-page sessions out of total sessions |
| **Session Duration** | Average time between a session's first event and its last activity |

::: tip
Bounce rate and session duration are computed server-side, so they remain accurate even if users close the tab without triggering a final event.
:::

## Breakdowns

Data in the dashboard can be broken down by a variety of dimensions to help you understand your audience.

### Event

| Dimension | Description |
|-----------|-------------|
| Event name | Group metrics by the name of the event (e.g., `screen_view`, `Purchase Completed`) |

### Geographic

| Dimension | Source |
|-----------|--------|
| Country | IP geolocation (server-side) |
| Region | IP geolocation (server-side) |
| City | IP geolocation (server-side) |

### Device & Browser

| Dimension | Source |
|-----------|--------|
| Browser | User agent parsing |
| Browser version | User agent parsing |
| OS | User agent parsing |
| OS version | User agent parsing |
| Device type | Desktop, mobile, or tablet (user agent parsing) |
| Brand | Device manufacturer (e.g., Apple, Samsung) |
| Model | Device model (e.g., iPhone 15, Pixel 8) |

### Pages & Traffic

| Dimension | Description |
|-----------|-------------|
| Page path | The URL path of the page where the event occurred |
| Referrer | The referring URL that brought the user to your site |
| UTM source | The `utm_source` query parameter |
| UTM medium | The `utm_medium` query parameter |
| UTM campaign | The `utm_campaign` query parameter |

## Timeline

View event trends over time by selecting a time interval. The timeline chart adjusts automatically based on your date range, but you can also set the interval manually:

| Interval | Best for |
|----------|----------|
| Hourly | Monitoring traffic within a single day |
| Daily | Viewing trends over days or weeks |
| Weekly | Comparing week-over-week performance |
| Monthly | Long-term trend analysis |

## Visitor activity heatmap

The activity tile answers *when* people visit, rather than how many did. Every cell is one hour of one day, shaded by how many distinct visitors started a visit in it — the darkest cell is the busiest hour in the grid, and the shading is relative to that, so the pattern reads the same whether you get a hundred visitors a week or a hundred thousand.

Rows can be grouped two ways:

| Rows | Answers |
|------|---------|
| **Weekday** | Which days and hours your site is busiest — all seven days are always shown, quiet ones included |
| **Country** | When each of your busiest countries shows up, which is usually their working day rather than yours |

A few things worth knowing:

* **Hours are yours.** Both the hour and the weekday are resolved in your browser's timezone, not UTC. Two people in different offices reading the same project see the same traffic bucketed against their own clocks.
* **At least a week.** A heatmap needs enough days to have a shape, so if the date range above is shorter than 7 days, the tile widens to the last 7 days and labels the window it used. Ranges wider than a week are used as selected.
* **Cells don't add up to your visitor total.** Each cell counts the distinct visitors in that hour. Somebody who visits on Monday and again on Tuesday is a visitor in both — counting them once would mean choosing a day to leave them out of.
* **Longer ranges stack weekdays.** Over 30 days, a Monday cell is every Monday in the window added together. When a range isn't a whole number of weeks, the weekday that occurs one extra time reads slightly higher.

## Filtering

Use the filter bar at the top of the dashboard to narrow down the data you see. Filters can be combined for precise analysis.

### Available Filters

| Filter | Description |
|--------|-------------|
| **Date range** | Select a start and end date for the data window |
| **Event name** | Show only specific events (e.g., `screen_view`, `Purchase Completed`) |
| **Channel** | Filter by event channel (e.g., `__analytics`, `payments`) |
| **Browser** | Filter by browser name or version |
| **Country** | Filter by geographic location |
| **Device type** | Filter by desktop, mobile, or tablet |
| **OS** | Filter by operating system |
| **Referrer** | Filter by traffic source |
| **UTM parameters** | Filter by UTM source, medium, or campaign |

Any dimension available in the breakdown view can also be used as a filter.

## Data Enrichment

When an event arrives at the Kitbase server, it is enriched with additional context before being stored. This enrichment happens entirely server-side.

| Raw Data | Enriched Result |
|----------|-----------------|
| User agent string | Device type, browser name and version, OS name and version, brand, and model |
| IP address | Country, region, and city (the IP itself is **not stored** unless explicitly configured) |
| Page URL | Path and referrer |
| URL query parameters | UTM source, medium, and campaign |

::: info IP Handling
By default, Kitbase does not persist raw IP addresses. Geolocation is resolved at ingestion time and only the resulting country, region, and city are stored.
:::

## Privacy

Kitbase is designed to be privacy-friendly by default:

* **No cookies** -- Analytics tracking does not use cookies of any kind.
* **localStorage for anonymous ID** -- A UUID is stored in localStorage to identify returning visitors. This can be disabled by setting `storage: null` in the SDK config.
* **No raw IP storage** -- IP addresses are resolved to country, region, and city at ingestion time. The raw IP itself is not stored.
* **Bot filtering** -- Automated traffic from crawlers, headless browsers, and testing tools is filtered out automatically.

## Next steps

* [Project Assistant](/guide/assistant) — ask about these metrics in plain language instead of building the breakdown yourself.
* [Events guide](/guide/events) — the raw feed behind these metrics.
* [Sessions guide](/guide/sessions) — visits, duration, and bounce rate.
* [Users guide](/guide/users) — profiles and identity resolution.
* [Web Analytics overview](/web-analytics) — how the data gets here in the first place.

---

---
url: 'https://docs.kitbase.dev/custom-dashboards.md'
description: >-
  Build your own charts from web traffic, crawlers, AI visibility and AI
  citations, and arrange them on a board your whole project shares.
---

# Custom Dashboards

The built-in reports answer the questions most teams have. A dashboard is where you put the ones your team has — the four numbers you check on Monday, side by side, instead of across four pages.

A dashboard belongs to a **project**, and everyone with access to that project sees it. That is deliberate: a board is how a team agrees on what to watch, which a private-by-default board would defeat.

::: info Availability
Custom dashboards are on every paid plan.
:::

## Building a chart

Every chart answers one question, assembled in the same order:

| Step | What it decides | Example |
|---|---|---|
| **Data source** | Which dataset the numbers come from | Web traffic |
| **Metric** | What is counted | Visitors |
| **Break down by** | Which column splits it (optional) | Country |
| **Over time** | The size of each bucket (optional) | By day |
| **Filters** | What is left out (optional) | Browser is not Safari |
| **Show as** | The picture | Line |

The preview redraws as you go, using exactly the same code path a saved chart uses — so a chart that previews is a chart that saves.

### What you can measure

| Source | Metrics | Break down by |
|---|---|---|
| **Web traffic** | Visitors, sessions, pageviews, bounce rate, average session duration, pages per session, revenue | Country, region, city, device, browser, OS, device brand and model, UTM source/medium/campaign, referrer, page |
| **Crawlers & AI bots** | Requests | Bot, vendor, country, path, category |
| **AI visibility** | Presence rate, mention rate, citation rate, citations, answers | Engine |
| **AI citations** | Citations | Domain, page |

Revenue charts show a currency symbol only when every revenue event in the window shares one currency; when the window mixes currencies — or none of the events named one — the figure is a plain number rather than a guessed symbol.

The lists are uneven on purpose. A metric is offered a breakdown or a time axis only where a real query stands behind it — bounce rate is a single number because nothing computes it per day, and visitors and pageviews take different page columns because Kitbase counts them differently. Offering the missing combinations would mean inventing a second calculation, and a chart that disagrees with the Web Analytics page is worse than a chart that does not exist.

::: tip The numbers match the reports
A chart reads through the same code the built-in reports read through. "Visitors by day" on a board and the Web Analytics timeline are the same query with the same window — they cannot drift apart.
:::

### Which pictures are available

The shape of the question decides the pictures, so options you cannot use are greyed out rather than refused after you save:

| Over time | Break down | You can draw |
|---|---|---|
| yes | no | Line, area, bar |
| yes | yes | Line, stacked area, stacked bar |
| no | yes | Bar, donut, table |
| no | no | Single number |

## The date range

The board has one date picker, and every chart on it answers for that range. A chart stores no dates of its own, so the same board shows last week or last quarter without editing anything on it — and the range lives in the URL, so a link to a board is a link to a board *at a particular window*.

Turning on **Compare** adds the previous period to every chart: a delta under a single number, a second column in a table, and a comparison total on a series.

A series reports its comparison as a total rather than as a second line, because the two windows need not be the same length — lining them up bucket for bucket would either drop points or invent them.

## Arranging the board

The grid is two columns. A chart is either half the board or the full width of it, and you drag charts to reorder them. Two columns keeps every card wide enough for axis labels you can actually read; on a phone the board becomes one column.

Up to **24 charts** fit on a board and **20 boards** on a project. Each chart is its own request, so the cap is really a limit on how many queries one page fires at once.

## Who can do what

| Action | Needs |
|---|---|
| See boards and their charts | Access to the project |
| Create, edit, arrange, delete | Owner or admin |

::: info Wider editing is coming
Building boards is limited to owners and admins in this first release, while the
previous dashboard code is still deployed alongside it. The release that removes
that code opens editing to developers and analysts.
:::

Permission to build a board is not permission to see everything on one. Each data source carries its own: someone without access to AI visibility cannot read AI numbers by putting them on a board, and sources they cannot read are not offered in the builder at all.

## Related

* [Analytics](/guide/analytics) — the built-in web traffic reports
* [Bot & Crawler Detection](/crawler-detection) — where the crawler numbers come from
* [AI Visibility](/ai-visibility) — where the AI presence and citation numbers come from

---

---
url: 'https://docs.kitbase.dev/guide/events.md'
description: >-
  Understand how events work in Kitbase, including event structure, types,
  channels, tags, and how to view them in the dashboard.
---

# Events

Events are the foundation of Kitbase analytics. Every interaction you want to measure -- a page view, a button click, a purchase, an error -- is represented as an event.

## What Are Events

An event is a record of something that happened in your application at a specific point in time. Events are sent to the Kitbase server, enriched with contextual data, and stored for analysis. You can view, filter, and break down events in the dashboard.

## Event Structure

Every event contains the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `event` | `string` | The name of the event (e.g., `"Purchase Completed"`, `"screen_view"`) |
| `channel` | `string` | A category that groups related events (e.g., `"payments"`, `"users"`, `"errors"`) |
| `tags` | `object` | Key-value metadata attached to the event (string, number, or boolean values) |
| `timestamp` | `string` | ISO 8601 timestamp of when the event occurred |
| `user_id` | `string` | The identified user who performed the action (set after `identify()`) |
| `anonymous_id` | `string` | The auto-generated UUID for anonymous tracking |
| `session_id` | `string` | The session during which the event occurred |

Additional optional fields include `icon`, `notify`, and `description` for display and notification purposes.

## Types of Events

### Auto-Tracked Events

These events are captured automatically by the SDK without any code on your part. They are sent to the `__analytics` channel.

| Event | Trigger | Description |
|-------|---------|-------------|
| `session_start` | A new session begins | Captures referrer, UTM parameters, and device info |
| `screen_view` | A page is loaded or a route changes | Captures page path, title, and referrer |
| `outbound_link` | A user clicks a link to an external domain | Captures the destination URL and link text |
| `scroll_depth` | The user scrolls past defined thresholds | Captures the maximum scroll percentage |
| `click` | A user clicks a tracked element | Captured via data attributes (see below) |

Auto-tracked events can be individually enabled or disabled in the SDK configuration. See [Autocapture](/autocapture) for the full reference.

### Custom Events

Custom events are tracked explicitly using the `track()` method. Use them for anything specific to your business logic.

```typescript
await kitbase.track({
  channel: 'payments',
  event: 'New Subscription',
  user_id: 'user-123',
  notify: true,
  tags: {
    plan: 'premium',
    amount: 9.99,
  },
});
```

See [Track Events](/track-events) for the complete API and examples.

### Data Attribute Events

Track user interactions directly from HTML without writing JavaScript. Add data attributes to any element:

| Attribute | Trigger | Description |
|-----------|---------|-------------|
| `data-kb-track-click` | Element is clicked | Sends a click event with the attribute value as the event name |
| `data-kb-track-visibility` | Element enters the viewport | Sends a visibility event when the element becomes visible |

```html
<button data-kb-track-click="CTA Clicked">Get Started</button>

<section data-kb-track-visibility="Pricing Section Viewed">
  <!-- pricing content -->
</section>
```

### Revenue Events

Track monetary values with the dedicated `trackRevenue()` method. Revenue events are aggregated in the dashboard for financial reporting.

```typescript
await kitbase.trackRevenue({
  amount: 99.99,
  currency: 'USD',
  orderId: 'order-123',
  productId: 'prod-456',
  tags: { plan: 'premium' },
});
```

## Channels

Channels are categories that organize your events into logical groups. They make it easy to filter and navigate events in the dashboard.

| Channel | Purpose |
|---------|---------|
| `__analytics` | System channel for auto-tracked events (page views, sessions, outbound links) |
| `payments` | Financial events such as subscriptions, purchases, and refunds |
| `users` | User lifecycle events like signups, logins, and profile updates |
| `errors` | Application errors, exceptions, and failure conditions |
| Custom channels | Any channel name relevant to your domain (e.g., `"notifications"`, `"api"`, `"features"`) |

::: tip Channel Naming
Use lowercase, plural nouns for channel names. This keeps your events organized and consistent across your codebase.
:::

## Tags

Tags are key-value pairs that attach rich metadata to your events. They allow you to slice and filter event data across any dimension you need.

### User-Defined Tags

You set these when calling `track()`. They support three value types:

| Type | Example |
|------|---------|
| `string` | `plan: 'premium'` |
| `number` | `amount: 99.99` |
| `boolean` | `is_first_purchase: true` |

```typescript
tags: {
  plan: 'premium',
  amount: 99.99,
  is_first_purchase: true,
}
```

### Server-Enriched Tags

The server automatically adds tags prefixed with `__` based on the incoming request. These are stored as first-class dimensions and are available as filters in the dashboard.

| Tag | Description |
|-----|-------------|
| `__browser` | Browser name |
| `__browser_version` | Browser version |
| `__os` | Operating system |
| `__os_version` | OS version |
| `__device` | Device type (desktop, mobile, tablet) |
| `__brand` | Device manufacturer |
| `__model` | Device model |
| `__country` | Country (from IP geolocation) |
| `__region` | Region or state |
| `__city` | City |
| `__path` | Page path |
| `__referrer` | Referrer URL |
| `__utm_source` | UTM source parameter |
| `__utm_medium` | UTM medium parameter |
| `__utm_campaign` | UTM campaign parameter |

### Super Properties

Super properties are tags that are automatically included in every event you send. Set them once and they persist for the duration of the session (or until cleared).

```typescript
kitbase.setSuperProperties({
  app_version: '2.1.0',
  environment: 'production',
});

// Now every track() call includes app_version and environment
```

See [Track Events — Super Properties](/track-events#super-properties) for more on super properties.

## Viewing Events

The Kitbase dashboard provides several ways to explore your event data.

### Event Timeline

View a chronological stream of events with configurable time intervals (hourly, daily, weekly, monthly). The timeline chart shows event volume over time and updates as you apply filters.

### Event Breakdown

Break down event counts by any dimension -- event name, browser, country, device type, page path, referrer, UTM parameters, and more. Use breakdowns to understand the composition of your traffic.

### Event Detail View

Click on any individual event to see its full detail, including:

* Event name and channel
* Timestamp
* User ID and anonymous ID
* Session ID
* All user-defined tags
* All server-enriched tags

### Filtering

Narrow down the event list using the filter bar:

* **Date range** -- Select a time window
* **Channel** -- Filter by event channel
* **Event name** -- Show only specific events
* **User** -- Search by user ID or anonymous ID
* **Dimensions** -- Filter by browser, country, device, OS, referrer, UTM parameters, and more

## Notifications

When you set `notify: true` on a tracked event, Kitbase sends a real-time alert. Use notifications for high-value or critical events.

```typescript
await kitbase.track({
  channel: 'payments',
  event: 'Payment Failed',
  user_id: 'user-123',
  icon: '🔴',
  notify: true,
  tags: {
    amount: 99.99,
    error: 'card_declined',
  },
});
```

Good candidates for notifications:

* New signups and subscriptions
* Failed payments
* Critical application errors
* Security events (e.g., login from a new device)

## Next steps

* [Track Events](/track-events) — send custom events from your code.
* [Autocapture](/autocapture) — the payload reference for every automatic event.
* [Sessions guide](/guide/sessions) — how events group into visits.

---

---
url: 'https://docs.kitbase.dev/guide/sessions.md'
description: >-
  Understand how sessions work in Kitbase, including session lifecycle,
  analytics, bounce rate, and SDK management.
---

# Sessions

A session represents a continuous period of user activity on your site. Sessions are the foundation for engagement metrics like bounce rate, session duration, and pages per session.

## What Is a Session

A session begins when a user first interacts with your site and ends after 30 minutes of inactivity. If the user returns after the timeout has elapsed, a new session is created. Sessions group related events together so you can understand user journeys as cohesive visits rather than isolated actions.

## Session Lifecycle

### Start

A session starts when:

* A user loads your site for the first time
* A user returns after the session timeout has elapsed (default: 30 minutes)
* `reset()` is called, which forces a new session

When a session starts, the SDK sends a `session_start` event to the `__analytics` channel with referrer, UTM parameters, and device information.

### Active

While the session is active, any user interaction (page view, click, custom event) resets the inactivity timer. The session remains open as long as the user continues interacting within the timeout window.

### End

A session ends after 30 minutes with no user activity. There is no explicit "session end" event -- the server determines session boundaries based on the time gap between events.

## Session Data

Each session contains the following data points:

| Field | Description |
|-------|-------------|
| **Session ID** | A unique UUID identifying the session |
| **Start time** | Timestamp of the first event in the session |
| **End time** | Timestamp of the last activity in the session |
| **Duration** | Time between the first and last event |
| **Event count** | Total number of events recorded during the session |
| **User ID** | The identified user (if `identify()` was called during the session) |
| **Browser** | Browser name and version |
| **OS** | Operating system name and version |
| **Device type** | Desktop, mobile, or tablet |
| **Country** | Country resolved from IP geolocation |
| **Region** | Region or state |
| **City** | City |
| **Pages visited** | List of page paths viewed during the session |

## Session Analytics

The Sessions page in the dashboard lets you explore sessions across your user base.

### Session List

View all sessions with filtering options:

| Filter | Description |
|--------|-------------|
| Date range | Select a time window |
| Country | Filter by geographic location |
| Browser | Filter by browser name |
| Device type | Filter by desktop, mobile, or tablet |
| User | Search sessions by user ID |

### Choosing Columns

Use the **Columns** button above the table to pick which columns the session list shows. Your selection is saved in the browser and reapplied the next time you open the page.

Session ID is always shown. Exit page, referrer, and ended at are available but hidden by default — enable them from the same menu. Once you've customized the list, a **Reset to default** action appears at the bottom of the menu.

### Session Detail

Click on any session to drill into its event timeline. The detail view shows every event that occurred during the session in chronological order, including:

* Event name and channel
* Timestamp
* Tags and metadata
* Page path

### Session Metrics

| Metric | Description |
|--------|-------------|
| Session duration distribution | Histogram showing how long sessions typically last |
| Events per session | Average number of events across sessions |
| Pages per session | Average number of distinct pages viewed |

## Bounce Rate

A "bounced" session is one where the user viewed only a single page before leaving. Bounce rate measures the percentage of these single-page sessions.

```
Bounce Rate = (Bounced Sessions / Total Sessions) x 100
```

A high bounce rate may indicate that users are not finding what they expect, or it may be normal for content like blog posts where a single page satisfies the visit. Interpret bounce rate in the context of your site's purpose.

## Session Management in the SDK

The SDK provides methods to inspect and control sessions programmatically.

### Get Session Info

```typescript
const session = kitbase.getSession();
// => {
//   id: 'sess_abc123',
//   startedAt: 1705321800000,
//   lastActivityAt: 1705323600000
// }
```

### Get Session ID

```typescript
const sessionId = kitbase.getSessionId();
// => 'sess_abc123'
```

### Force a New Session

```typescript
kitbase.reset();
// Ends the current session and starts a new one
// Also clears the user ID (if set via identify)
```

## Next steps

* [Users guide](/guide/users) — how sessions group into people.
* [Autocapture](/autocapture#session-start) — `session_start` / `session_end` payloads.
* [Analytics dashboard guide](/guide/analytics) — session metrics in context.

---

---
url: 'https://docs.kitbase.dev/guide/users.md'
description: >-
  Understand how Kitbase tracks anonymous and identified users, identity
  resolution, user properties, and the user analytics dashboard.
---

# Users

Kitbase tracks two types of users: anonymous users who have not been identified, and identified users who have been linked to a known user ID via the `identify()` method.

## User Types

| Type | Identifier | How It Works |
|------|-----------|--------------|
| **Anonymous** | `anonymous_id` (auto-generated UUID) | Created automatically on first visit. Each device gets its own anonymous ID. |
| **Identified** | `user_id` (your identifier) | Linked to a known user via `identify()`. Associates all activity with a single identity. |

## Anonymous Tracking

When a user first visits your site, the SDK automatically generates a UUID and stores it in localStorage. This anonymous ID is attached to every event the user triggers.

```typescript
// Anonymous ID is generated and included automatically
await kitbase.track({
  channel: 'engagement',
  event: 'Landing Page Viewed',
});

// Retrieve the current anonymous ID
const anonymousId = kitbase.getAnonymousId();
// => "550e8400-e29b-41d4-a716-446655440000"
```

Key points about anonymous tracking:

* The UUID is generated on the user's first visit.
* It is stored in localStorage, so it persists across page loads and browser restarts.
* All events are attributed to this `anonymous_id` until the user is identified.
* Each device gets its own `anonymous_id`. A user on two devices will appear as two anonymous users until `identify()` is called on both.

### Disabling Storage

If you do not want to persist the anonymous ID across page loads, disable storage:

```typescript
const kitbase = init({
  sdkKey: '<YOUR_API_KEY>',
  storage: null, // Anonymous ID regenerated each session
});
```

## User Identification

Call `identify()` after a user logs in or signs up to link their anonymous activity to a known user ID.

```typescript
await kitbase.identify({
  userId: 'user-123',
  traits: {
    email: 'jane@example.com',
    name: 'Jane Doe',
    plan: 'premium',
  },
});
```

When `identify()` is called:

1. The SDK sends the current `anonymous_id` and the provided `userId` to the server.
2. The server creates a link between the two identifiers.
3. All past events associated with that `anonymous_id` are backfilled with the `user_id`.
4. All subsequent events automatically include the `user_id`.

### Multi-Device Identification

When the same user logs in on multiple devices, each device has its own `anonymous_id`. Calling `identify()` on each device links all anonymous IDs to the same `user_id`, unifying the user's activity across devices.

```typescript
// Device A: anonymous_id = "aaa-111"
await kitbase.identify({ userId: 'user-123' });
// => aaa-111 linked to user-123

// Device B: anonymous_id = "bbb-222"
await kitbase.identify({ userId: 'user-123' });
// => bbb-222 also linked to user-123

// Both devices' events are now attributed to user-123
```

## User Analytics Dashboard

The Users page in the dashboard gives you a complete view of your user base.

### User List

Browse all users with the following controls:

| Control | Description |
|---------|-------------|
| **Type filter** | Show all users, only identified users, or only anonymous users |
| **Search** | Search by user ID or anonymous ID |
| **Country filter** | Filter by geographic location |
| **Browser filter** | Filter by browser name |
| **Date range** | Filter by when users were first or last seen |

### Choosing Columns

Use the **Columns** button above the table to pick which columns the user list shows. Your selection is saved in the browser and reapplied the next time you open the page.

User ID is always shown. The Type column only appears on the **All** tab, since the Identified and Anonymous tabs already contain a single user type. Once you've customized the list, a **Reset to default** action appears at the bottom of the menu.

### User Detail View

Click on any user to see their full profile:

| Section | Description |
|---------|-------------|
| **User type** | Whether the user is identified or anonymous |
| **Session count** | Total number of sessions recorded for this user |
| **Event count** | Total number of events triggered by this user |
| **First seen** | Timestamp of the user's earliest event |
| **Last seen** | Timestamp of the user's most recent event |
| **User properties** | Traits set via `identify()` (email, name, plan, etc.) |
| **Activity heatmap** | A calendar heatmap showing events per day over recent months |
| **Event history** | A chronological list of all events with timestamps and details |

## User Properties (Traits)

Traits are key-value pairs that describe the user. They are set through the `identify()` method and are visible in the user detail view.

```typescript
await kitbase.identify({
  userId: 'user-123',
  traits: {
    email: 'jane@example.com',
    name: 'Jane Doe',
    company: 'Acme Corp',
    plan: 'premium',
    created_at: '2025-01-15T10:00:00Z',
  },
});
```

Traits can be updated at any time by calling `identify()` again with the same `userId` and new or changed values:

```typescript
// User upgrades their plan
await kitbase.identify({
  userId: 'user-123',
  traits: {
    plan: 'enterprise',
  },
});
```

The new traits are merged with existing ones. You do not need to resend all traits on every call.

## Identity Resolution

Identity resolution is the process of connecting anonymous and identified user records into a single profile.

### How It Works

1. **Before `identify()`** -- The user is tracked under their `anonymous_id`. All events are attributed to this anonymous identifier.
2. **When `identify()` is called** -- The server creates a mapping from `anonymous_id` to `user_id`.
3. **Backfill** -- All past events that were recorded with the `anonymous_id` are retroactively associated with the `user_id`.
4. **Response** -- The server response indicates whether this was a new link or a previously established one.

This ensures accurate Monthly Active User (MAU) counts. A user who browses anonymously and later creates an account is counted as one user, not two.

::: tip
Identity resolution prevents double-counting. Without it, a user who visits your site anonymously and then signs up would appear as two separate users in your analytics.
:::

## Best Practices

### Use Database IDs as user\_id

Use your application's internal database ID or UUID as the `userId`, not personally identifiable information like email addresses. This avoids leaking PII into analytics and keeps the identifier stable even if the user changes their email.

```typescript
// Recommended
await kitbase.identify({ userId: user.databaseId });

// Avoid
await kitbase.identify({ userId: user.email });
```

### Call identify() Early

Call `identify()` as soon as the user is authenticated. This ensures that events triggered immediately after login are correctly attributed.

```typescript
async function handleLogin(credentials) {
  const user = await authService.login(credentials);

  // Identify immediately after authentication
  await kitbase.identify({
    userId: user.id,
    traits: {
      email: user.email,
      name: user.name,
      plan: user.subscription?.plan,
    },
  });
}
```

### Update Traits on Profile Changes

When user properties change (e.g., plan upgrade, name change), call `identify()` again to keep traits current.

```typescript
async function handlePlanUpgrade(newPlan) {
  await kitbase.identify({
    userId: currentUser.id,
    traits: { plan: newPlan },
  });
}
```

### Call reset() on Logout

When a user logs out, call `reset()` to clear the user ID and generate a new anonymous ID. This prevents the next user on the same device from being attributed to the previous user's identity.

```typescript
function handleLogout() {
  kitbase.reset();
  // Clears user_id, generates a new anonymous_id, starts a new session
}
```

### Be Consistent with user\_id Format

Use the same format for `userId` across all platforms and services. If you use a database integer ID on the web, use the same ID in your mobile app and backend. Inconsistent formats lead to fragmented user profiles.

```typescript
// Consistent: always use the database ID
userId: String(user.id) // "12345" everywhere

// Inconsistent: different formats in different places
userId: user.id         // "12345" on web
userId: user.email      // "jane@example.com" on mobile
```

## Next steps

* [Identify Users](/identify-users) — the `identify()` call that powers these profiles.
* [Sessions guide](/guide/sessions) — the visits that make up each user history.
* [Dashboard guide](/guide/) — all four dashboard views.

---

---
url: 'https://docs.kitbase.dev/guide/account-security.md'
description: >-
  Two-factor authentication, passkeys and backup codes in Kitbase, and how an
  organization's 2FA requirement is enforced against each session.
---

# Account Security

Kitbase supports three second factors, all managed under **Account Settings → Security**.

| Factor | What it proves | Notes |
|--------|----------------|-------|
| **Authenticator app (TOTP)** | Something you have | Six-digit codes from Google Authenticator, 1Password, Authy, … |
| **Passkey** | Something you have + something you are | Touch ID, Windows Hello, or a hardware security key. Phishing-resistant: a passkey will not sign you in on a look-alike domain |
| **Backup codes** | A one-time escape hatch | Ten single-use codes, issued when you enable TOTP |

Backup codes are exactly single-use. Once a code is spent it cannot be spent again, including by a second attempt made at the same moment — so a code someone else has seen is worth nothing once you have used it. Regenerating codes invalidates every previous one.

## Signing in with a passkey

A passkey can sign you in on its own, with no password, provided your device actually verified you — a fingerprint, a face, or a device PIN. That is already two factors: possession of the device plus proof you are its owner.

If your device does *not* verify you (an unlocked security key with no PIN, for example), the assertion proves possession and nothing more. Kitbase treats that as a single factor:

* If you have an authenticator app enrolled, you are asked for a code before the sign-in completes.
* Otherwise you are signed in, but the session counts as single-factor for the rule below.

## Organizations that require 2FA

An organization owner can require two-factor authentication for everyone in the organization, under **Organization Settings → Security**.

**The requirement is checked against your current session, not against your account.** This is the part worth understanding, because it explains both of the surprising cases:

* Enrolling an authenticator app is not enough on its own. If you then sign in with **only a password**, that session used one factor and the organization refuses it — you will see `ORG_007` on every page. Sign in again and complete the second step.
* You do **not** need an authenticator app if you use a passkey. A passkey sign-in that verified you already satisfies the requirement, so passkey-only members are not forced to also enrol TOTP.

The same rule follows a session wherever it goes. Refreshing keeps whatever factor the original sign-in used — it neither loses nor gains one — and a [CLI session](/cli) inherits the strength of the browser session that approved it, so approve CLI logins from a session that used your second factor.

::: tip Turning the requirement on
Members already signed in are not kicked out the moment you enable it. Their existing sessions continue until they expire, and every sign-in after that must satisfy the requirement.
:::

## Disabling two-factor authentication

Removing your authenticator app needs your password and a current code (or a backup code). If any organization you belong to requires 2FA, Kitbase refuses and names the organizations, so you know why.

## Next steps

* [CLI authentication](/cli#authentication) — how a terminal session is authorised
* [MCP connections](/sdks/mcp#authentication) — granting an AI assistant scoped access

---

---
url: 'https://docs.kitbase.dev/crawler-detection.md'
description: >-
  Detect AI crawlers and bots (GPTBot, Googlebot, ClaudeBot, …) that never run
  the JavaScript SDK by forwarding your server or edge requests to Kitbase. Pick
  your platform for a copy-paste setup guide.
---

# Bot & Crawler Detection

Tag-based analytics only sees clients that execute JavaScript, so non-JS crawlers — GPTBot, Googlebot, ClaudeBot, PerplexityBot, scrapers — are invisible to it. Forward your **server or edge requests** to Kitbase and they're classified server-side: bot and crawler traffic is stored with full attribution, while human requests are ignored (the JS SDK already counts them).

## Detection vs. filtering {#detection-vs-filtering}

Kitbase has two bot features that point in opposite directions — this page is about the first one:

| | **Bot & Crawler Detection** (this page) | **Bot filtering** (built into [web analytics](/web-analytics)) |
|---|---|---|
| Goal | Make bots **visible** — see which crawlers and AI bots visit your site | Keep bots **out** of your human analytics |
| Where it runs | Your server or edge, forwarding requests to Kitbase | The JS SDK in the browser, plus the server-side pipeline |
| What happens to bots | Stored as their own dataset with attribution (name, vendor, verified/spoofed) | Silently discarded — never reach your dashboards or billing counts |
| Setup | Opt-in: install a forwarder for your platform (below) | Automatic — [no configuration](/autocapture#bot-filtering) |

Both use the same [attribution pipeline](/track-events#bot-crawler-attribution) to decide *what's a bot* — they just do opposite things with the answer. And neither is [AI Visibility](/ai-visibility), which tracks how AI **answers** mention your brand, not which AI **crawlers** visit your site.

::: tip Guided setup in the dashboard
The first time you open the **Crawlers** page in the dashboard (under **AI visibility** in the project sidebar), a setup wizard walks you through the whole flow — creating a secret API key, installing the forwarder for your platform, and live-verifying that the first request and first detected crawler arrive.
:::

Pick your platform to get a copy-paste setup guide:

## How it works

Every platform does the same thing: it observes the **original visitor's** request signals (User-Agent, IP, path, …) and POSTs them to Kitbase's ingestion endpoint. Kitbase runs its [bot & crawler attribution pipeline](/track-events#bot-crawler-attribution) — including cryptographic [Web Bot Auth](/track-events#bot-crawler-attribution) verification when present — and stores the bot/crawler requests.

* **Endpoint:** `POST https://ingest.kitbase.dev/ingest/v1/server` (Vercel uses a [Log Drain](/crawler-detection/vercel) instead).
* **Auth:** your **secret** API key (`sk_kitbase_…`) as `Authorization: Bearer <key>` — never the browser-exposed SDK key. The key resolves your project, which is the target for everything you send.
* **Humans are ignored**, so it's safe to forward every request; only bots/crawlers are stored, and only when events are enabled for the project.

::: info Privacy — we only keep the bots
Forwarding every request doesn't mean every request is stored. Human visitors' signals are used only to classify the request in memory and are then **discarded** — only bot and crawler requests are persisted. For those, the raw IP is stored only when IP logging is enabled for the project; otherwise it's used to derive geolocation (country, region, city) and then dropped.
:::

## Comparing periods {#compare-periods}

The crawler reports read from the same date window as the rest of your analytics, and compare against an earlier one the same way — against the previous period unless `comparePreset`, or a `compareFrom`/`compareTo` pair, names another. [Compare to an earlier period](/web-analytics#compare-periods) covers what each preset means, the guard rails, and how the extra response fields read; only the shapes below are specific to crawlers.

| Report | What a comparison adds |
|---|---|
| `GET /bots/analytics/timeline` | `comparisonSeries` — the same per-vendor series over the earlier window, at the same interval. A vendor that only crawled in one of the two windows has a series in that one alone |
| `GET /bots/analytics/top` | `previousRequestCount` per bot, with `absoluteChange` and `percentageChange` |
| `GET /bots/analytics/countries` | `previousRequestCount` and `previousBotCount` per country; the change fields describe requests, the metric the list is ranked on |
| `GET /bots/analytics/categories` | `previousRequestCount` per actor category, under the same `search` and `actorType` filters |
| `GET /bots/analytics/top-paths` | `previousRequestCount` per path, under the same `vendor` filter |

A crawler that first showed up inside your selected period reads `previousRequestCount: 0` — it was there to be counted and wasn't — while one that has since stopped crawling is simply not listed, because the ranking is the selected period's.

## Kitbase's own crawler {#kitbaseauditbot}

If your project has a [website connected](/guide/analytics#connect-a-website-optional), Kitbase's own crawler — **KitbaseAuditBot** (`Mozilla/5.0 (compatible; KitbaseAuditBot/1.0; +https://kitbase.dev/audit-bot)`) — fetches your public pages to power Site Audit and page indexing. With a forwarder installed you'll see it in the Crawlers page like any other bot, and it holds itself to the same standard we detect others by:

* Every request is signed with **Web Bot Auth** (RFC 9421 HTTP Message Signatures, Ed25519). Kitbase's detection pipeline verifies the signature, so KitbaseAuditBot always shows as **verified** — and a request that fakes its user-agent without a valid signature is flagged as suspected or spoofed.
* The public key directory is published at `https://kitbase.dev/.well-known/http-message-signatures-directory`, so any third-party detector that implements Web Bot Auth can verify it the same way.
* Verified KitbaseAuditBot requests are stored for visibility but **never count toward your bot-event usage** — you aren't billed for traffic Kitbase generates.

See the full request schema and response in the [API reference](/api-reference#server-side-crawler-detection).

---

---
url: 'https://docs.kitbase.dev/crawler-detection/nextjs.md'
description: >-
  Detect GPTBot, Googlebot, ClaudeBot, and other non-JS crawlers in your Next.js
  app by forwarding Edge middleware requests to Kitbase.
---

# Next.js Bot & Crawler Detection

Detect crawlers and AI bots that never run the JavaScript SDK (GPTBot, Googlebot, ClaudeBot, scrapers, …) directly from Next.js [Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware). The middleware runs in the Edge runtime on every matched request and forwards the visitor's signals to Kitbase, which classifies the actor server-side and stores bot/crawler traffic with full attribution. Human requests are ignored, so it's safe to run on every request.

::: info Privacy — we only keep the bots
Forwarding every request doesn't mean every request is stored. Human visitors' signals are used only to classify the request in memory and are then **discarded** — only bot and crawler requests are persisted. For those, the raw IP is stored only when IP logging is enabled for the project; otherwise it's used to derive geolocation (country, region, city) and then dropped.
:::

## Prerequisites

Set a server-only environment variable (**don't** prefix it with `NEXT_PUBLIC_`):

* `KITBASE_API_KEY` — your project's **secret** API key (`sk_kitbase_…`), not the browser SDK key.

## Setup

Add a `middleware.ts` file at your project root (or in `src/`). Forward with `event.waitUntil` so the page response is never delayed. (`request.ip` was removed in Next.js 15, so the client IP is read from `x-forwarded-for`.)

```ts
// middleware.ts
import { NextResponse, type NextRequest, type NextFetchEvent } from "next/server";

export function middleware(request: NextRequest, event: NextFetchEvent) {
  const fwd = request.headers.get("x-forwarded-for");
  event.waitUntil(
    fetch("https://ingest.kitbase.dev/ingest/v1/server", {
      method: "POST",
      headers: { authorization: `Bearer ${process.env.KITBASE_API_KEY}`, "content-type": "application/json" },
      body: JSON.stringify({ events: [{
        user_agent: request.headers.get("user-agent"),
        ip_address: fwd?.split(",")[0]?.trim(),
        method: request.method,
        host: request.headers.get("host"),
        path: request.nextUrl.pathname,
        referrer: request.headers.get("referer"),
        signature: request.headers.get("signature"),
        signature_input: request.headers.get("signature-input"),
        signature_agent: request.headers.get("signature-agent"),
      }]}),
    }).catch(() => {}), // never block the response
  );

  return NextResponse.next();
}

export const config = {
  // Page requests only — skip static assets and Next internals to avoid noise.
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};
```

The `signature*` headers are part of [Web Bot Auth](/track-events#bot-crawler-attribution) — forwarding them lets Kitbase cryptographically verify a crawler's claimed identity when present.

::: tip Hosted on Vercel?
You can skip middleware entirely and use a [Vercel Log Drain](/crawler-detection/vercel) — it captures crawler requests (static + edge) with zero code.
:::

## Next steps

* [API reference](/api-reference#server-side-crawler-detection) — full request schema, response, and attribution fields.
* [All platforms](/crawler-detection) — setup guides for other frameworks and hosts.

---

---
url: 'https://docs.kitbase.dev/crawler-detection/tanstack-start.md'
description: >-
  Detect GPTBot, Googlebot, and other non-JS crawlers in TanStack Start using a
  global request middleware that forwards SSR requests to Kitbase.
---

# TanStack Start Bot & Crawler Detection

Crawler detection runs server-side, so this applies to **TanStack Start** (SSR). Register a [global request middleware](https://tanstack.com/start/latest/docs/framework/react/guide/middleware#global-request-middleware) — it runs on every server request, including the SSR document loads that non-JS crawlers fetch — and forward the visitor's signals to Kitbase. Bot/crawler traffic is stored with attribution; human requests are ignored.

::: info Privacy — we only keep the bots
Forwarding every request doesn't mean every request is stored. Human visitors' signals are used only to classify the request in memory and are then **discarded** — only bot and crawler requests are persisted. For those, the raw IP is stored only when IP logging is enabled for the project; otherwise it's used to derive geolocation (country, region, city) and then dropped.
:::

## Prerequisites

Set an environment variable on your server:

* `KITBASE_API_KEY` — your project's **secret** API key (`sk_kitbase_…`), not the browser SDK key.

## Setup

Create a `src/start.ts` file (it isn't in the default template) and register the middleware globally:

```ts
// src/start.ts
import { createStart, createMiddleware } from "@tanstack/react-start";

const crawlerIngest = createMiddleware().server(({ next, request }) => {
  const url = new URL(request.url);
  const fwd = request.headers.get("x-forwarded-for");
  fetch("https://ingest.kitbase.dev/ingest/v1/server", {
    method: "POST",
    headers: { authorization: `Bearer ${process.env.KITBASE_API_KEY}`, "content-type": "application/json" },
    body: JSON.stringify({ events: [{
      user_agent: request.headers.get("user-agent"),
      ip_address: fwd?.split(",")[0]?.trim(),
      method: request.method,
      host: url.host,
      path: url.pathname,
      referrer: request.headers.get("referer"),
      signature: request.headers.get("signature"),
      signature_input: request.headers.get("signature-input"),
      signature_agent: request.headers.get("signature-agent"),
    }]}),
  }).catch(() => {}); // fire-and-forget; never block SSR

  return next();
});

export const startInstance = createStart(() => ({
  requestMiddleware: [crawlerIngest],
}));
```

The `signature*` headers are part of [Web Bot Auth](/track-events#bot-crawler-attribution) — forwarding them lets Kitbase cryptographically verify a crawler's claimed identity when present.

::: warning Using TanStack Router as a client-only SPA (no SSR)?
A non-JS crawler only ever receives your static `index.html` and never runs the bundle, so the router can't observe it. Forward from whatever serves that HTML instead — your [Node/Express](/crawler-detection/node-express) or [Cloudflare](/crawler-detection/cloudflare-workers) host, or, on Vercel, a [Log Drain](/crawler-detection/vercel).
:::

## Next steps

* [API reference](/api-reference#server-side-crawler-detection) — full request schema, response, and attribution fields.
* [All platforms](/crawler-detection) — setup guides for other frameworks and hosts.

---

---
url: 'https://docs.kitbase.dev/crawler-detection/node-express.md'
description: >-
  Detect GPTBot, Googlebot, and other non-JS crawlers in a Node.js or Express
  app by forwarding request signals to Kitbase from middleware.
---

# Node.js & Express Bot & Crawler Detection

Detect crawlers and AI bots that never run the JavaScript SDK by adding a small middleware to your Express (or any Node.js) app. It forwards each request's signals to Kitbase, which classifies the actor and stores bot/crawler traffic with attribution. Human requests are ignored.

::: info Privacy — we only keep the bots
Forwarding every request doesn't mean every request is stored. Human visitors' signals are used only to classify the request in memory and are then **discarded** — only bot and crawler requests are persisted. For those, the raw IP is stored only when IP logging is enabled for the project; otherwise it's used to derive geolocation (country, region, city) and then dropped.
:::

## Prerequisites

Set an environment variable:

* `KITBASE_API_KEY` — your project's **secret** API key (`sk_kitbase_…`), not the browser SDK key.

## Setup

Mount the middleware early, before your routes. The IP comes from `x-forwarded-for` (when behind a proxy/load balancer) and falls back to the socket address. Make sure [`trust proxy`](https://expressjs.com/en/guide/behind-proxies.html) is set if you terminate TLS at a load balancer.

```js
app.use((req, res, next) => {
  fetch("https://ingest.kitbase.dev/ingest/v1/server", {
    method: "POST",
    headers: { "authorization": `Bearer ${process.env.KITBASE_API_KEY}`, "content-type": "application/json" },
    body: JSON.stringify({ events: [{
      user_agent: req.headers["user-agent"],
      ip_address: req.headers["x-forwarded-for"]?.split(",")[0]?.trim() || req.socket.remoteAddress,
      method: req.method,
      host: req.headers.host,
      path: req.path,
      referrer: req.headers.referer,
      signature: req.headers["signature"],
      signature_input: req.headers["signature-input"],
      signature_agent: req.headers["signature-agent"],
    }]}),
  }).catch(() => {}); // fire-and-forget; never block the response
  next();
});
```

For high-traffic apps, buffer observed requests and send them in batches (up to **500** per call) on a short interval instead of one request per call.

The `signature*` headers are part of [Web Bot Auth](/track-events#bot-crawler-attribution) — forwarding them lets Kitbase cryptographically verify a crawler's claimed identity when present.

## Next steps

* [API reference](/api-reference#server-side-crawler-detection) — full request schema, response, and attribution fields.
* [All platforms](/crawler-detection) — setup guides for other frameworks and hosts.

---

---
url: 'https://docs.kitbase.dev/crawler-detection/wordpress.md'
description: >-
  Detect GPTBot, Googlebot, and other non-JS crawlers on a WordPress site by
  forwarding request signals to Kitbase from a small must-use plugin.
---

# WordPress Bot & Crawler Detection

Detect crawlers and AI bots that never run the JavaScript SDK by dropping a small [must-use plugin](https://wordpress.org/documentation/article/must-use-plugins/) into your WordPress site. It forwards each front-end request's signals to Kitbase, which classifies the actor and stores bot/crawler traffic with attribution. Human requests are ignored.

A must-use plugin (mu-plugin) runs on every request, loads before regular plugins, and can't be deactivated from the admin — so your bot coverage survives theme switches and plugin changes. You can also paste the same snippet into your theme's `functions.php`, but an mu-plugin is theme-independent and recommended.

::: info Privacy — we only keep the bots
Forwarding every request doesn't mean every request is stored. Human visitors' signals are used only to classify the request in memory and are then **discarded** — only bot and crawler requests are persisted. For those, the raw IP is stored only when IP logging is enabled for the project; otherwise it's used to derive geolocation (country, region, city) and then dropped.
:::

## Prerequisites

Add a constant to `wp-config.php` (above the `/* That's all, stop editing! */` line):

```php
define( 'KITBASE_API_KEY', 'sk_kitbase_…' ); // your project's SECRET key, not the browser SDK key
```

## Setup

Create `wp-content/mu-plugins/kitbase-crawler.php` (make the `mu-plugins` folder if it doesn't exist). The request is sent non-blocking, so it never adds latency to your page load.

```php
<?php
/**
 * Plugin Name: Kitbase Crawler Detection
 * Description: Forwards front-end request signals to Kitbase for server-side bot & crawler detection.
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

add_action( 'template_redirect', function () {
	// Only forward real front-end page requests.
	if ( is_admin() || wp_doing_cron() || wp_doing_ajax() ) {
		return;
	}

	$server = $_SERVER;

	// Behind a proxy/CDN, the visitor IP is the first entry of X-Forwarded-For.
	$ip = $server['REMOTE_ADDR'] ?? null;
	if ( ! empty( $server['HTTP_X_FORWARDED_FOR'] ) ) {
		$ip = trim( explode( ',', $server['HTTP_X_FORWARDED_FOR'] )[0] );
	}

	$body = array(
		'events' => array(
			array(
				'user_agent'      => $server['HTTP_USER_AGENT'] ?? null,
				'ip_address'      => $ip,
				'method'          => $server['REQUEST_METHOD'] ?? null,
				'host'            => $server['HTTP_HOST'] ?? null,
				'path'            => wp_parse_url( $server['REQUEST_URI'] ?? '', PHP_URL_PATH ),
				'referrer'        => $server['HTTP_REFERER'] ?? null,
				'signature'       => $server['HTTP_SIGNATURE'] ?? null,
				'signature_input' => $server['HTTP_SIGNATURE_INPUT'] ?? null,
				'signature_agent' => $server['HTTP_SIGNATURE_AGENT'] ?? null,
			),
		),
	);

	// Fire-and-forget: blocking => false never delays the response.
	wp_remote_post( 'https://ingest.kitbase.dev/ingest/v1/server', array(
		'blocking'  => false,
		'timeout'   => 1,
		'headers'   => array(
			'Authorization' => 'Bearer ' . KITBASE_API_KEY,
			'Content-Type'  => 'application/json',
		),
		'body'      => wp_json_encode( $body ),
	) );
} );
```

That's it — no build step, no admin screen. The next crawler to hit your site shows up in Kitbase.

The `signature*` headers are part of [Web Bot Auth](/track-events#bot-crawler-attribution) — forwarding them lets Kitbase cryptographically verify a crawler's claimed identity when present.

::: tip High-traffic sites
`wp_remote_post` opens one non-blocking HTTP request per page view. On busy sites, prefer buffering signals (e.g. to an object cache or a log) and shipping them in batches of up to **500** on a short interval — see the [nginx guide](/crawler-detection/nginx) for the log-and-ship pattern.
:::

## Next steps

* [API reference](/api-reference#server-side-crawler-detection) — full request schema, response, and attribution fields.
* [All platforms](/crawler-detection) — setup guides for other frameworks and hosts.

---

---
url: 'https://docs.kitbase.dev/crawler-detection/cloudflare-workers.md'
description: >-
  Detect GPTBot, Googlebot, and other non-JS crawlers from a Cloudflare Worker
  by forwarding request signals to Kitbase with waitUntil.
---

# Cloudflare Workers Bot & Crawler Detection

Detect crawlers and AI bots that never run the JavaScript SDK from a Cloudflare Worker sitting in front of your origin. The Worker serves the page first, then forwards the visitor's signals to Kitbase with `ctx.waitUntil` so analytics never adds latency. Cloudflare resolves the true client IP in `cf-connecting-ip`.

::: info Privacy — we only keep the bots
Forwarding every request doesn't mean every request is stored. Human visitors' signals are used only to classify the request in memory and are then **discarded** — only bot and crawler requests are persisted. For those, the raw IP is stored only when IP logging is enabled for the project; otherwise it's used to derive geolocation (country, region, city) and then dropped.
:::

## Prerequisites

Add a [Worker environment variable / secret](https://developers.cloudflare.com/workers/configuration/secrets/):

* `KITBASE_API_KEY` — your project's **secret** API key (`sk_kitbase_…`), not the browser SDK key.

## Setup

```js
export default {
  async fetch(request, env, ctx) {
    const response = await fetch(request); // serve the page first
    ctx.waitUntil(fetch("https://ingest.kitbase.dev/ingest/v1/server", {
      method: "POST",
      headers: { "authorization": `Bearer ${env.KITBASE_API_KEY}`, "content-type": "application/json" },
      body: JSON.stringify({ events: [{
        user_agent: request.headers.get("user-agent"),
        ip_address: request.headers.get("cf-connecting-ip"),
        method: request.method,
        host: new URL(request.url).host,
        path: new URL(request.url).pathname,
        referrer: request.headers.get("referer"),
        signature: request.headers.get("signature"),
        signature_input: request.headers.get("signature-input"),
        signature_agent: request.headers.get("signature-agent"),
      }]}),
    }));
    return response;
  },
};
```

The `signature*` headers are part of [Web Bot Auth](/track-events#bot-crawler-attribution) — forwarding them lets Kitbase cryptographically verify a crawler's claimed identity when present.

## Next steps

* [API reference](/api-reference#server-side-crawler-detection) — full request schema, response, and attribution fields.
* [All platforms](/crawler-detection) — setup guides for other frameworks and hosts.

---

---
url: 'https://docs.kitbase.dev/crawler-detection/vercel.md'
description: >-
  Detect GPTBot, Googlebot, and other non-JS crawlers on Vercel with zero code
  by pointing a Vercel Log Drain at Kitbase.
---

# Vercel Bot & Crawler Detection

If your site is hosted on Vercel, point a **Log Drain** at Kitbase to capture every request — including crawlers that never run JavaScript — **without adding any code**. Vercel POSTs batches of request logs; Kitbase reads each log's `proxy` object (`clientIp`, `userAgent`, `method`, `host`, `path`, `referer`), classifies the actor, and stores bot/crawler requests. Human requests are ignored.

```
POST https://ingest.kitbase.dev/ingest/v1/vercel
```

::: info Privacy — we only keep the bots
Forwarding every request doesn't mean every request is stored. Human visitors' signals are used only to classify the request in memory and are then **discarded** — only bot and crawler requests are persisted. For those, the raw IP is stored only when IP logging is enabled for the project; otherwise it's used to derive geolocation (country, region, city) and then dropped.
:::

## Setup

1. Go to **Vercel → your Project or Team → Settings → Log Drains** (or use the Vercel API).
2. **Endpoint:** `https://ingest.kitbase.dev/ingest/v1/vercel` — your secret API key (step 5) resolves the target project.
3. **Sources:** select **Static** and **Edge** (add **Function** if you render on-demand).
4. **Delivery format:** JSON or NDJSON — both are accepted.
5. **Custom header:** add `Authorization: Bearer sk_kitbase_<your_secret_api_key>`. This authenticates the drain and resolves your project. Use the **secret** API key, not the SDK key.
6. **Endpoint verification:** Vercel performs a one-time ownership check; Kitbase responds to it automatically via the `x-vercel-verify` header.

::: tip Self-hosting Kitbase?
Set the `INGEST_VERCEL_VERIFY` environment variable on your Kitbase server to the verification value Vercel shows when creating the drain, so your endpoint echoes it back in the `x-vercel-verify` response header.
:::

## Response

`200 OK` — `{ "accepted": <stored bots>, "received": <request logs parsed> }`. Non-request logs (build/function output without a `proxy` object) are ignored.

## Next steps

* [API reference](/api-reference#vercel-log-drain) — endpoint details and response schema.
* [All platforms](/crawler-detection) — setup guides for other frameworks and hosts.

---

---
url: 'https://docs.kitbase.dev/crawler-detection/cloudfront.md'
description: >-
  Detect GPTBot, Googlebot, and other non-JS crawlers on an AWS/Amplify site
  with zero code by streaming CloudFront standard logs to Kitbase through Amazon
  Data Firehose.
---

# AWS CloudFront Bot & Crawler Detection

If your site is served through **AWS CloudFront** — including sites hosted on **AWS Amplify** — stream CloudFront's **standard access logs** to Kitbase through **Amazon Data Firehose** to capture every request, including crawlers that never run JavaScript, **without adding any code**. Firehose POSTs batches of log records; Kitbase reads each CloudFront log's fields (`c-ip`, `cs-user-agent`, `cs-method`, `x-host-header`, `cs-uri-stem`, `cs-referer`), classifies the actor, and stores bot/crawler requests. Human requests are ignored.

```
POST https://ingest.kitbase.dev/ingest/v1/cloudfront
```

```
Amplify / your origin ──► CloudFront ──standard logs v2──► Amazon Data Firehose ──► Kitbase
```

::: info Amplify sites need your own CloudFront
AWS Amplify already serves through a CloudFront distribution, but it isn't one you can attach logging to. Put **your own** CloudFront distribution in front of the Amplify app (Amplify origin), then enable logging on that distribution.
:::

::: info Privacy — we only keep the bots
Forwarding every request doesn't mean every request is stored. Human visitors' signals are used only to classify the request in memory and are then **discarded** — only bot and crawler requests are persisted. For those, the raw IP is stored only when IP logging is enabled for the project; otherwise it's used to derive geolocation (country, region, city) and then dropped.
:::

## Setup

You need three things: a CloudFront distribution, a Firehose delivery stream pointed at Kitbase, and CloudFront **standard logging v2** wired to that stream.

1. **CloudFront distribution** — front your origin (the Amplify app's `*.amplifyapp.com` domain, or any origin) with a CloudFront distribution. If you serve a custom domain (e.g. `home.example.com`), add it to both CloudFront (with an ACM cert in **us-east-1**) and — for Amplify origins — to the Amplify app, so the forwarded `Host` header resolves.

2. **Amazon Data Firehose stream** (Direct PUT) with an **HTTP endpoint** destination:
   * **Endpoint URL:** `https://ingest.kitbase.dev/ingest/v1/cloudfront` — your secret API key (the access key below) resolves the target project.
   * **Access key:** set it to your **secret** API key, `sk_kitbase_<your_secret_api_key>`. Firehose sends it in the `X-Amz-Firehose-Access-Key` header; Kitbase uses it to authenticate the stream and resolve your project. Use the **secret** key, not the browser-exposed SDK key.
   * **Buffering:** 60 s / 1 MB is a good default (near-real-time).
   * **Backup:** enable *failed-data-only* S3 backup so nothing is lost if the endpoint is briefly unavailable.

3. **CloudFront standard logging v2** → your Firehose stream. Set **Output format** to **JSON**, and select these fields (CloudFront uses the W3C `cs(Header)` spelling): `timestamp`, `c-ip`, `sc-status`, `cs-method`, `cs-uri-stem`, `cs-uri-query`, `cs(Host)`, `cs(User-Agent)`, `cs(Referer)`, `sc-content-type`.

That's it — CloudFront delivers access logs to Firehose, Firehose batches and POSTs them to Kitbase, and bot/crawler requests show up in your dashboard.

::: tip Tip — standard logging v2, not real-time logs
Use CloudFront **standard logging v2** (delivered to Firehose), not real-time logs. Real-time logs require a Kinesis Data Stream, which adds a baseline hourly cost; standard logging v2 has no such baseline — you pay only for Firehose ingestion, which the AWS free tier covers at low volume.
:::

## Response

`200 OK` — Firehose's required acknowledgement, `{ "requestId": "…", "timestamp": <ms> }`. Log rows without a usable client IP and User-Agent are ignored. A non-2xx response makes Firehose retry the batch and, after retries, park it in the stream's S3 backup.

## Next steps

* [API reference](/api-reference#aws-cloudfront-standard-logs) — endpoint details and response schema.
* [All platforms](/crawler-detection) — setup guides for other frameworks and hosts.

---

---
url: 'https://docs.kitbase.dev/crawler-detection/nginx.md'
description: >-
  Detect GPTBot, Googlebot, and other non-JS crawlers behind nginx by logging
  request signals as JSON and shipping them to Kitbase in batches.
---

# nginx Bot & Crawler Detection

nginx doesn't call out to an API per request without extra modules, so the reliable pattern is: **log** the signals Kitbase needs as structured JSON, then **ship** them to the ingestion endpoint in batches.

::: info Privacy — we only keep the bots
Forwarding every request doesn't mean every request is stored. Human visitors' signals are used only to classify the request in memory and are then **discarded** — only bot and crawler requests are persisted. For those, the raw IP is stored only when IP logging is enabled for the project; otherwise it's used to derive geolocation (country, region, city) and then dropped.
:::

## Prerequisites

* `KITBASE_API_KEY` — your project's **secret** API key (`sk_kitbase_…`).

## 1. Log the signals as JSON

Add a JSON `log_format` and write it to a dedicated access log. (`$uri` is the normalized path; the client timestamp is omitted so Kitbase stamps each event at receipt time.)

```nginx
log_format kitbase escape=json '{'
    '"user_agent":"$http_user_agent",'
    '"ip_address":"$remote_addr",'
    '"method":"$request_method",'
    '"host":"$host",'
    '"path":"$uri",'
    '"referrer":"$http_referer"'
'}';

access_log /var/log/nginx/kitbase.log kitbase;
```

If nginx sits behind another proxy/load balancer, use `$http_x_forwarded_for` (first IP) for `ip_address` instead of `$remote_addr`.

## 2. Ship the log to Kitbase

Use a log shipper to read new lines and POST them to `https://ingest.kitbase.dev/ingest/v1/server` in batches (up to **500** per call). A production-grade shipper like [Vector](https://vector.dev) or [Fluent Bit](https://fluentbit.io) with an HTTP sink handles tailing, rotation, and batching for you — point it at the endpoint with the `Authorization: Bearer` header and wrap the lines as `{ "events": [ ... ] }`.

For a minimal setup, a tiny tailer works too:

```js
// kitbase-shipper.js — tail the nginx JSON log and POST batches
import { spawn } from "node:child_process";

const tail = spawn("tail", ["-n0", "-F", "/var/log/nginx/kitbase.log"]);
let buffer = [];

async function flush() {
  if (buffer.length === 0) return;
  const events = buffer.splice(0, 500);
  await fetch("https://ingest.kitbase.dev/ingest/v1/server", {
    method: "POST",
    headers: { authorization: `Bearer ${process.env.KITBASE_API_KEY}`, "content-type": "application/json" },
    body: JSON.stringify({ events }),
  }).catch(() => {});
}

tail.stdout.on("data", (chunk) => {
  for (const line of chunk.toString().split("\n")) {
    if (line.trim()) try { buffer.push(JSON.parse(line)); } catch {}
  }
});

setInterval(flush, 5000); // flush every 5s
```

Human requests in the batch are ignored by Kitbase — only bot/crawler requests are stored.

## Next steps

* [API reference](/api-reference#server-side-crawler-detection) — full request schema, response, and attribution fields.
* [All platforms](/crawler-detection) — setup guides for other frameworks and hosts.

---

---
url: 'https://docs.kitbase.dev/ai-visibility.md'
description: >-
  Track how often AI platforms (Perplexity, Google Gemini, Claude, ChatGPT)
  mention your brand, which domains they cite, and how you compare to
  competitors.
---

# AI Visibility

AI platforms are becoming a discovery channel: people ask Perplexity, Gemini, Claude, or ChatGPT "what's the best X?" instead of scrolling search results. AI Visibility is the rank tracker for those answers — it queries the platforms with the prompts your buyers actually ask and measures three things:

* **Presence rate** — the share of answers that mention your brand (or cite your domain), tracked over time.
* **Cited-domain map** — which websites the platforms cite as sources, classified as **yours**, a **competitor's**, or **other** (review sites, Reddit, editorial). These are the pages that shape AI answers about your category.
* **Per-platform breakdown** — how Perplexity, Gemini, Claude, and ChatGPT compare, so you know where you're strong and where you're invisible.

Everything runs against the platforms' official APIs — no scraping.

::: info Not the same as Bot & Crawler Detection
AI Visibility measures how AI **answers** talk about your brand. To see which AI **crawlers** (GPTBot, ClaudeBot, PerplexityBot, …) visit your website, use [Bot & Crawler Detection](/crawler-detection) — the two are unrelated datasets.
:::

## Setup

AI Visibility is configured per project under **AI visibility → Visibility** in the project sidebar.

### 1. Configure provider API keys (server)

The analysis calls provider APIs with keys configured on the Kitbase server. A search provider with no key is simply disabled — with one exception: **`GEMINI_API_KEY` is required** to run analyses at all, because beyond powering Gemini it also runs the answer-analysis pass that extracts brand mentions from every answer (a separate, non-grounded `gemini-2.5-flash` call). Without it, starting an analysis is rejected and scheduled runs are skipped.

| Env var | Provider | Notes |
|---|---|---|
| `PERPLEXITY_API_KEY` | Perplexity Sonar | Uses the `sonar` model; citations and actual request cost come back in the response |
| `GEMINI_API_KEY` | Google Gemini | Uses Search grounding; cost is estimated from configured rates |
| `ANTHROPIC_API_KEY` | Claude | Uses the Messages API's `web_search` tool; cost is computed from real token + search usage in the response |
| `OPENAI_API_KEY` | ChatGPT | Uses the Responses API's `web_search` tool; cost is computed from real token + search usage in the response |

On Kitbase Cloud, **which platforms your analyses run against is set by your plan** — Starter tracks ChatGPT; Pro adds Gemini and Perplexity; Business covers every available answer platform. Per-organization overrides are supported.

Self-hosted deployments supply their own keys and run against every platform they've configured. Model names, per-minute rate limits, cost rates, and the default monthly spend cap are configurable under the `ai-visibility:` section of the server config; on Kitbase Cloud the monthly limit is set per plan.

### 2. Add your brand and competitors

Create one **self brand** (your product) with:

* **Primary domain** — the registrable domain (e.g. `example.com`). Citations of this domain count as self-citations and classify the domain map. If the project has a website connected (set at project creation or on the project's **Website** page), the field is prefilled with it — a brand can still use a different domain than the tracked site.
* **Aliases** — alternative names the platforms might use (`Kitbase`, `kitbase.dev`, …). An extraction model parses every answer into the full list of companies it names; those extracted names are then matched to your brands by name, alias, or domain — so add the spellings and short forms the platforms actually use.

Add competitor brands the same way (name + domain + aliases) to see them in the domain map and mention data. You don't have to know them all up front — once analyses run, **Suggested competitors** proposes brands the AI itself named that you aren't tracking, and one click adds them here (see [Reading the results](#reading-the-results)). **Brand changes apply retroactively**: adding, renaming, or removing a brand (or its aliases) automatically re-matches your stored analysis history against the new list, so a newly added competitor appears with its full history instead of starting from zero — no re-run and no extra AI cost.

#### Tracking a competitor only in some topics

Competitor sets are rarely uniform across everything you measure. A brand may compete directly with you on one topic and be irrelevant on another, where its appearance in answers is noise that inflates its rank and dilutes everyone's share of voice.

Each competitor on the setup page carries a **topic scope** next to its domain — *All topics* by default, or *N topics excluded*. Open it to uncheck the topics that competitor should not be measured in.

An excluded competitor is treated as **not existing** for the runs of that topic, rather than as present zero percent of the time. In practice:

* Those runs leave the competitor's **denominator** as well as its numerator, so its visibility rate reads over the topics it is actually tracked in.
* It contributes nothing to share of voice on those topics — the remaining brands re-normalise to 100%.
* Filter the results to a topic it is excluded from and it disappears from the competitor leaderboard, the trends chart, share of voice, and the topics breakdown entirely.
* Prompts with **no topic** always count. Only real topics can be excluded.

The scope is applied when results are read, not when answers are analysed, so it applies to your whole stored history the moment you change it and costs nothing to undo — re-check a topic and the competitor's full history is back. Archiving a topic leaves its exclusions in force over the runs already tagged with it, so past numbers don't silently move.

### 3. Add prompts

Prompts are the questions your buyers ask AI platforms — e.g. *"best session replay tool for startups"*, *"Kitbase vs PostHog"*, *"how do I track AI crawler traffic"*. Add them in bulk (one per line).

Once you have a few, the prompts page lets you work on several at once: tick the rows you want and the summary strip turns into a toolbar that can **move them to a topic** or **delete them**. Both apply as a single transaction — if one prompt in the selection can't be changed, none of them are.

**Deleting is how you remove a prompt, and it is permanent.** The prompt's answers go with it, and every period it ran in loses its contribution to the numbers — a deleted prompt stops shaping last month's figures as well as next month's. If you want a prompt to stop running but keep its history and its place in past periods, set `active: false` on it instead — through the API, or through the `active` column of the spreadsheet the prompts page can download and re-upload. Prompts switched off that way still appear in the table, struck through, so they stay reachable.

On Kitbase Cloud the number of **active prompts per project is plan-limited** (per-organization overrides supported). Prompts with `active: false` keep their historical data and don't count against the limit. AI visibility is also limited to a set number of **projects per organization** by plan (Starter 1, Pro 2, Business 5; overrides supported) — a project claims a slot once it has its first active prompt. Self-hosted deployments use the configured server cap instead.

### 4. Add personas (optional)

A **persona** is the buyer you're tracking for: a name plus a few sentences on what they're trying to do, what gets in their way, and the words they'd actually type into an AI assistant — *"Ops lead at a 3PL. Drowning in manual freight paperwork. Searches things like 'cheapest way to automate freight documents'."*

Personas do two things, and only these two:

1. **They shape the prompts you write.** Ask for prompt suggestions with a persona selected and the generated questions carry that buyer's situation as context — *"best freight automation for a 40-person 3PL"*. Each suggestion comes back labelled with the persona it was written for, a one-line reason, and a suggested intent tier, so you can tell what you're about to spend a prompt slot on.
2. **They group your results.** Every prompt belongs to exactly one persona, so each answer lands in exactly one bucket and per-persona share of voice adds up to your whole result set. That's what makes "we're strong with ops leads and invisible to CFOs" a statement you can trust rather than an artefact of double-counting.

**A persona is never sent to an AI platform.** It doesn't change what we ask, it isn't a roleplay instruction, and it doesn't multiply what a run costs — two personas on the same question is still one question. This is deliberate: prompts phrased as roleplay ("You are an IT consultant…") pull answers toward general explanation and away from naming products, which would move your visibility number instead of segmenting it.

Personas are a simulated buyer lens, not observed demand. They describe how *we'd expect* a given buyer to ask — no tool can show you what real people typed into ChatGPT.

You can draft personas with AI from your brand and domain, but drafts are never saved on their own: you edit and accept each one. An unreviewed auto-generated persona comes out broad enough ("Marketing Manager") that it produces the same generic prompts as no persona at all. Two or three specific personas beat a long list. On Kitbase Cloud the number of **active personas per project is plan-limited**; archiving one frees a slot, keeps past runs resolving, and frees the name for reuse.

Prompts written before you added personas have no persona attached. The setup screen offers a one-click **backfill** that applies each prompt's current persona to its past runs, so historical comparisons aren't split in half by the day you started using them.

### 5. Regions (set by support)

By default every project is measured from the **United States** — that's the vantage point AI platforms answer from, and it's what a project runs unless support adds more.

A **region** is the unit you are measured in — `US` or `EU`. Some regions span more than one country internally; which ones is server configuration (`ai-visibility.regions.*`), so self-hosted deployments can redefine what a region spans.

Each prompt runs **once per region**. Where a region spans several countries your prompts are spread across them and the answers roll back up to the region, so a multi-country region costs one pass, not one per country. A given prompt always lands in the same place, so its trend line compares like with like run over run.

That makes the multiplier the **number of regions** you track: adding `EU` to a US-only project doubles its included responses, not quadruples them. Regions are part of your Business plan and are priced into it — they never use credits.

On Kitbase Cloud the region set is **configured per organization by support** — contact them to add one. It is not something you turn on yourself, precisely because each region multiplies what every project in your organization runs per check. Every project in the organization measures from the whole set, and the Setup tab shows you which regions are running and the countries behind each.

An added region joins your next daily check. A removed region keeps running until the first day of the next month, so a month you started with it is completed with it. Self-hosted deployments have every region available.

Once more than one region is live, every result view can be **filtered by region**, and each individual run records both the region it reports under and the exact country it queried.

## Prompt Explorer

**AI visibility → Explorer** answers "what does AI say about us *right now?*" without any of the setup above. Type a question, tick up to four platforms, and every answer lands side by side in about ten seconds.

Nothing here is tracked. The question is not added to your prompt set, the answers never enter presence rate, share of voice, or any other measurement, and running one has no effect on your trend lines. It exists for the two moments the tracked product is bad at: the first five minutes with a new project, and the middle of writing a prompt when you want to know what it actually returns before committing to measuring it.

Each answer column carries:

* the **platform and model** that produced it, and whether that is a **model API** answer or a **consumer surface**. These are not the same evidence — the ChatGPT API answers as a configured model, which is not what a person sees on chatgpt.com — so the label is on every card rather than left to be inferred from the platform name.
* **the brands it named**, split into yours and competitors, when *Detect your tracked brands* is on. Same extraction pass the tracked runs use.
* **the sources it cited**, and **the searches the platform actually ran** — often the most useful part, because a prompt about "best event lead capture software" is frequently answered by searching for something else entirely.
* **Highlight a brand** takes any name at all, tracked or not, and reports whether each answer and each source names it. Use it on a prospect's brand, a competitor nobody has configured yet, or a product you are merely curious about.

**Track this prompt** on the results header adds the question to your tracked set, where it starts building a trend from the next analysis. That is the path this feature exists to open: try it, then track it.

### What it costs

Prompt Explorer is an **extra**: every question spends credits — one provider call per platform, plus one extraction call per platform when brand detection is on — and shows its credit cost before you confirm. It never touches your included daily tracking. Three things keep the spend bounded:

* **An identical question is free for seven days.** Same prompt, same region, same platforms, same server-side settings reuses the stored answers and calls no platform. Cards served that way are marked **Cached answer**. **Run fresh** deliberately bypasses it and pays again.
* **A per-organization daily cap** limits how many explorations can be started in a rolling 24 hours, independent of the monthly budget.
* **Up to four platforms** per question.

Which platforms you can explore with is a plan setting, and it is deliberately **separate from the platforms your tracked analyses use**: you can ask the API engines your plan does not track (Gemini, Perplexity, Claude, DeepSeek, GLM, Kimi, by plan) per question, in credits — a way to see an engine's answers before adding it to your plan. Google AI Overviews / AI Mode and the web versions of ChatGPT and Gemini are tracking-only and cannot be asked interactively. The picker only ever shows what your plan actually allows; if it is empty, contact support.

Explorations are shared across your project's users (so a colleague opening one costs nothing) and are deleted automatically after 30 days. **Recent explorations**, above the answers, is the way back to any of them — opening one re-reads the stored answers and pays nothing.

Platforms settle independently: if one is busy or down, its column says so while the others show their answers. Region selection follows the same rule as tracked runs — a region samples one of its countries, so `EU` is a European reading rather than an exact-country choice, and there is no web-search toggle because search behaviour is decided per platform by the server.

Requires the `aivisibility.manage` permission, since it spends money.

## Running an analysis

**On Kitbase Cloud with an active paid subscription, analyses run automatically every 24 hours** — the dashboard shows a countdown to the next run in place of the run button. An automatic run only starts once the project is fully configured (your own brand plus at least one active prompt) and holds a **tracking slot** (Starter tracks 1 project, Pro 2; a project takes its slot when its first prompt is activated).

### What the plan includes

The daily check is **included in your plan and never uses credits**. One prompt checked on one engine in one region, once a day, is one **response**; your plan includes a number of tracked prompts — shared across your tracking projects — on a set of engines, checked daily. Starter: 25 prompts on ChatGPT, 750 responses per 30 days. Pro: 50 prompts on ChatGPT, Gemini and Perplexity, 4,500. Billing shows this month's responses used out of the month's allowance (calendar months vary, so the monthly figure does).

Included tracking pauses in exactly three cases, and you are told each time: today's included responses are used up (resumes at the next check), the project holds no tracking slot, or we paused it ourselves for a provider-safety problem on our side. It never stops because you ran out of credits.

**Changing your plan mid-month:** anything that gives you more — an upgrade, an added engine, more prompts — applies from your next daily check, prorated; nothing is back-filled. Anything that gives you less applies at the end of your paid period, and the calendar month you are in is completed at the old allowance. Your plan's prompts, engines and cadence never change mid-term because a provider changed its prices.

### Running one now

**Run analysis** outside the daily schedule is an **extra**: it uses credits, shows its credit cost before you confirm, and is refused when you have none left — your daily tracking is unaffected either way. On trials and self-hosted deployments the run button is the only way to run.

**Suspended organizations** keep read access to their AI visibility data and get a **single lifetime analysis** to try the feature. Once that run is used, starting another analysis (or requesting prompt suggestions) returns `BILLING_018` until the plan is upgraded; the full reset is also unavailable while suspended.

Each analysis is a background **job** with one unit of work per (prompt × platform). Jobs are:

* **Resumable** — completed provider calls are recorded and never re-executed, so a server restart or deploy mid-run resumes from where it left off instead of re-paying for finished queries.
* **Pausable** — pause settles after the current batch; resume continues with the remaining prompts only.
* **Cancellable** — cancelling keeps the results of already-completed units.

Only one analysis can be active per project. Each completed job becomes one data point in the presence-rate chart, so the daily automatic run (or a regular manual click) builds your trend line. AI answers are non-deterministic — treat single runs as samples and read the trend, not one day's number.

## Reading the results

**Visibility by persona** breaks the same window down by buyer, one row per persona plus a row for prompts with no persona, with each tracked brand's share of voice and visibility rate inside that persona's prompts. Because the rows partition your runs rather than overlapping, they are directly comparable with each other and reconcile to your project totals.

* **Presence rate** counts a prompt as "present" when the answer mentions any of your aliases **or** cites your primary domain. Filter by platform or view the combined rate. The presence series and per-platform breakdown also report the **mentioned** and **cited** rates separately, so you can see whether platforms talk about you, link to you, or both.
* **Presence by platform over time** plots one line per AI platform (Perplexity, Gemini, Claude, ChatGPT) across your completed analyses, so you can see which platforms are picking you up — and which are trailing — as your presence trends. Toggle between the **presence** and **cited** rate.
* **Competitor trends over time** plots one line per tracked brand (you plus your top competitors), so you can watch how your presence or citation rate moves against theirs run over run, not just at a single point in time.
* **Share of voice** normalizes each brand's presence against the total across all tracked brands per run, with a rank over time — a competitive share, not just your own rate.
* **Suggested competitors** surfaces brands the AI named on its own that you aren't tracking yet — extracted from each answer during the analysis pass and ranked by how many runs mentioned each. Anything you already track (your brand or a competitor, by name or alias) is filtered out, so the list is purely new discoveries. Click **Track** on one to start measuring it against you: it moves straight onto the competitors leaderboard from the next run.
* **Cited domains** aggregates citations across recent runs. Domains classified **OTHER** with high citation counts are where the platforms get their information — prime targets for content or PR. Each domain also carries a **source type** (UGC, review-site, news, reference, social, docs, editorial, or vendor) from a curated list, so you can see which kinds of sources shape answers in your category.
* **Cited pages** lists the exact pages (URLs) the platforms cited, across every domain, most-cited first — each with its page title, domain, source type, and the platforms that cited it. Switch the scope to **Mentioning you** to only count citations from answers where your brand appeared: those are the pages the platforms lean on when they talk about you, and the best places to be present (or to pitch).
* **Framing** — the extraction pass labels every detected mention with **sentiment** (positive / neutral / negative) and whether the answer **recommends** the brand versus merely mentioning it. When the answer presents a ranked list, it also records the brand's **position** within it.
* **Per-prompt breakdown** shows presence (and the analysis signals) for every prompt across each platform — a prompt × platform heatmap of where you win and lose.
* **Answers** is its own tab: every answer the platforms gave, newest first, one row each. Search for a word in the prompt or the answer (the excerpt lands on the hit), then narrow by platform, region, topic, which tracked competitors the answer named, where your brand landed in it (listed first, top 3, top 5, mentioned at all, or absent), and how the mention read (positive / neutral / negative). Every filter is in the URL, so a slice of answers is a link you can send. Clicking a row opens the full run drill-down.
* **Sponsored placements** shows who is *buying* ad slots inside the AI answers for your prompts. Google sells placements within AI Mode and AI Overview answers, and ChatGPT sells them inside its own answers; each advertiser is classified against your tracked brands the same way a cited domain is — so the panel answers the question that matters: *is a competitor paying for the answer you already rank in?* Every number is scoped to the platforms that can report ads at all (AI Mode, AI Overview, ChatGPT), so a zero means no ads were shown, never "we didn't look". ChatGPT also reports which ads were actually *displayed*: an ad the model was served but never put on screen is excluded from these counts, because nobody saw it. Each advertiser carries its ad headline and description, which is the competitor's own paid positioning, refreshed on every run.
* **Run drill-down** shows the full answer text, extracted citations, and detected brand mentions for any individual query — including each mention's sentiment, recommended flag, and rank — useful for verifying matches and understanding phrasing. When the answer carried advertising, the sponsored results are listed alongside it.

### How detection works

Each answer is processed once, right after it's collected: an extraction model parses the full answer text into a structured list of **every company or product it names**, each with its sentiment, recommendation status, list position, and any domain the answer ties to it. That extraction is stored per run. Matching extracted names to *your* tracked brands then happens in plain code (by name, alias, or primary domain) — which is why brand edits re-match history instantly without any new AI calls, and why untracked names can surface as **Suggested competitors**. Citations are matched separately by comparing each cited domain to your brands' primary domains.

The analysis signals (sentiment, recommended, rank, source type, mentioned/cited split) are populated for jobs run after the feature shipped; older jobs report them as **not analyzed** (null) rather than zero, so mixed-window charts don't understate rates. Runs from before the extraction pipeline keep their original mention data and are not re-matched on brand changes.

Tracking runs also feed Kitbase's aggregated public statistics at [kitbase.dev/data](https://kitbase.dev/data) — which domains each AI engine cites most, how often it cites anything at all, and how many sources an answer carries. Those pages publish percentages pooled across every customer and nothing else: no counts, and nothing that identifies a customer, project, prompt, brand, or end user. Your own domain is excluded from your own answers before anything is aggregated.

## Tracking a new brand (reset)

To start over with a different brand, open **Setup → Danger zone → Reset AI Visibility**. The reset permanently deletes the project's entire AI Visibility state: all analysis history (jobs, runs, answers, citations, mentions, and metrics) **and** all configuration (your brand, competitors, and prompts). Any running analysis is stopped. Afterwards the project returns to the setup wizard so you can configure the new brand from scratch. Requires the `aivisibility.manage` permission and cannot be undone.

## API

All endpoints live under `/{orgSlug}/projects/{projectId}/ai-visibility/` and require a bearer token. Viewing requires the `aivisibility.view` permission; configuration and job control require `aivisibility.manage`.

| Method & path | Purpose |
|---|---|
| `DELETE ` (feature root) | Full reset: deletes all history and configuration to start tracking a new brand |
| `GET/POST /brands`, `PUT/DELETE /brands/{brandId}` | Brand + competitor CRUD. `aliases` and `excludedTopicIds` are part of the payload and are **replaced wholesale** — send the full set on every write, or an omitted one clears it. `excludedTopicIds` is rejected for the self brand |
| `GET/POST /prompts`, `PUT/DELETE /prompts/{promptId}` | Prompt CRUD (`POST` is bulk and accepts `topicId`/`personaId` for the new prompts; `DELETE` is permanent — the prompt's runs and metrics go with it, so past periods lose its contribution. To stop a prompt but keep its history, `PUT` it with `active: false`). `PUT` replaces the prompt's own fields only and never touches its topic or persona — move those with the two calls below |
| `POST /prompts/bulk-move` | Moves up to 500 prompts into one topic in a single transaction — `{"promptIds": [...], "topicId": "…"}`, with an omitted or null `topicId` moving them out of every topic. All or nothing: an unknown prompt id, or a topic that isn't an active topic of this project, fails the call and moves nothing. Pass a single id to move one prompt |
| `POST /prompts/bulk-assign-persona` | Assigns one persona to up to 500 prompts — `{"promptIds": [...], "personaId": "…"}`, with an omitted or null `personaId` unassigning them. Same all-or-nothing rule, and the call never touches their topic or text. Separate from the move because each call owns one column, which is what lets null mean "unassign" on both without a flag saying whether the other was meant to be left alone |
| `POST /prompts/bulk-delete` | Permanently deletes up to 500 prompts — `{"promptIds": [...]}` — with the same cascade as a single `DELETE`. All or nothing, for the same reason |
| `POST /prompts/suggest` | Candidate prompts for a brand, not persisted. Pass `personaIds` to write them for specific buyers; each suggestion returns its `personaId`, a `reason`, and a suggested `intentTier` |
| `GET/POST /topics`, `PUT/DELETE /topics/{topicId}` | Topic CRUD (`DELETE` archives: prompts are uncategorized, history keeps resolving the topic) |
| `POST /topics/backfill` | Applies each prompt's current topic to its pre-topic runs. `{"dryRun": true}` returns only `eligibleRuns` |
| `GET/POST /personas`, `PUT/DELETE /personas/{personaId}` | Persona CRUD (`DELETE` archives: prompts are unassigned, history keeps resolving the persona). Plan-limited per project |
| `POST /personas/suggest` | Drafts 2-3 candidate personas from a brand name and domain. Nothing is persisted — save the ones you want via `POST /personas` |
| `POST /personas/backfill` | Applies each prompt's current persona to its pre-persona runs. `{"dryRun": true}` returns only `eligibleRuns` |
| `GET /topics-breakdown?jobs=10` | Per-topic visibility and share of voice, one row per topic plus an uncategorized bucket |
| `GET /personas-breakdown?jobs=10` | Per-persona visibility and share of voice, one row per persona plus a no-persona bucket. Rows partition the window, so their shares are directly comparable |
| `GET /jobs/estimate` | Pre-run summary: active prompt count, the platforms that will run, and whether the run is allowed |
| `GET /schedule` | Auto-run schedule state: whether automatic runs are enabled, when the next run is due (`nextRunAt`, `secondsUntilNextRun`), and whether a manual run is currently allowed |
| `POST /jobs` | Start an analysis job |
| `GET /jobs`, `GET /jobs/{jobId}` | Job history and live progress, incl. the platforms each job ran (`providers`) |
| `GET /jobs/{jobId}/runs?regions=US` | The job's per-(prompt × platform × region) runs (each carries its `promptId`, `region`, and the `market` country actually queried) |
| `GET /regions` | Regions this project is measured from, each with the countries it covers. Never empty (`US` at minimum). Read-only — the set is granted per organization by support, so there is no write endpoint |
| `POST /jobs/{jobId}/pause` · `/resume` · `/cancel` | Job control |
| `GET /visibility?provider=ALL&limit=30` | Presence-rate series per job, incl. `runsWithMention` / `runsWithCitation` and derived `mentionRate` / `citationRate` |
| `GET /provider-series?limit=30` | Presence series per job **split by platform** — one entry per AI provider (self brand), each with `presenceRate` / `citationRate` / `mentionRate`. Powers the per-platform trend chart |
| `GET /competitor-series?provider=ALL&limit=30` | Presence series per job **split by brand** — one entry per tracked brand (self + competitors), each with `presenceRate` / `citationRate` and normalized `shareOfVoice`. Powers the competitor trend chart |
| `GET /domains?provider=ALL&jobs=10&limit=25` | Cited-domain map over recent jobs, incl. `sourceType`, the citing `providers` (AI platforms), and `citationShare` — the domain's share (`0`–`1`) of **every** citation the window recorded, not only the domains on this page. Null when the window recorded no citations at all |
| `GET /domains/{domain}/citations?provider=ALL&jobs=10&page=0&size=20` | Drill-in for one cited domain: totals, citing `providers`, and the paginated list of exact cited URLs |
| `GET /citations/pages?provider=ALL&mentioningBrand=false&jobs=10&page=0&size=20` | Flat cited-pages list across all domains, most-cited first, each with `domain`, `title`, `classification`, `sourceType`, the citing `providers`, and `citationShare` — the page's share (`0`–`1`) of every citation the window recorded, taken against the same denominator the domain map uses. `mentioningBrand=true` only counts citations from answers where your brand appeared |
| `GET /breakdown?jobs=10` | Per-platform comparison, incl. mentioned/cited splits, sentiment counts, `recommendedRate`, and `avgAnswerRank` |
| `GET /competitors?jobs=10&limit=25&provider=ALL` | Every tracked brand ranked, incl. `shareOfVoice`, `mentionRate`, `citationRate`, `recommendedRate`, `avgAnswerRank`, rank buckets, and sentiment counts |
| `GET /discovered-competitors?jobs=10&limit=25&provider=ALL&topics=&regions=` | Suggested (untracked) competitors the AI named organically, ranked by `mentionCount` (distinct runs), with the citing `providers` and a best-effort `primaryDomain`. Already-tracked brands are excluded. Track one via `POST /brands` |
| `GET /share-of-voice?provider=ALL&jobs=10` | Per-job share-of-voice series: each brand's normalized share and dense rank |
| `GET /prompts-breakdown?jobs=10` | Per-prompt breakdown with an overall rollup plus one cell per platform |
| `GET /answers?page=0&size=20&search=&brandIds=&position=&sentiments=` | Project-wide answer list, newest first. Takes every shared filter plus four of its own: `search` (a word in the prompt or answer text), `brandIds` (answers naming any of these tracked brands), `position` (`FIRST` / `TOP_3` / `TOP_5` / `MENTIONED` / `NOT_MENTIONED` for your own brand), and `sentiments` (how your brand's mention read). Each row carries an `excerpt`, your brand's outcome (`selfPresent` / `mentioned` / `cited` / `answerRank` / `sentiment`), and every tracked brand the answer named |
| `GET /prompts/{promptId}/runs?provider=ALL&regions=US` | Recent answers for one prompt (a fixed-size history), each with its `region` and `market` |
| `GET /paid-placements?provider=&jobs=10` | Advertising shown inside the AI answers, over the same job window as every other read. Returns `advertisers` (domain, `classification`, `placementCount`, `promptCount`, the platforms, and a sample ad headline/description) and `prompts` (which of your prompts drew ads, how many `competitorAdvertisers`, and `selfMentioned` — whether your brand was named organically in an ad-carrying answer). `promptsMeasured` / `runsMeasured` are the denominators, counted only over platforms that can report ads. Ads a platform reported as served but never displayed are excluded from every count |
| `POST /paid-placements/backfill` | Re-reads the responses already stored on this project's runs (SERP and ChatGPT alike) to recover the placements they carried. Never calls a provider, so it costs nothing and is safe to re-run. `{"dryRun": true}` returns only `eligibleRuns`. Also repairs runs whose stored answer turned out to be the ad block (`answersRepaired`), which leaves those runs unanalyzed until they are extracted again. Requires `aivisibility.manage` |
| `GET /exploration-providers` | The platforms Prompt Explorer can actually run against for this organization: the server's configured **synchronous** adapters intersected with the plan's exploration platforms. Deliberately different from the platforms tracked analyses use — render the explorer's picker from this, never from a hardcoded list or from the tracking set |
| `POST /explorations` | Runs one ad-hoc prompt against 1–4 platforms synchronously and returns every answer with its citations, tracked-brand mentions, fan-out queries and cache provenance. Body: `promptText`, `providers[]`, optional `region`, `analyze` (default true), `highlightBrand`, `runFresh`. **Spends provider budget on every call**, is subject to a per-organization daily cap on top of the monthly budget, and reuses an identical question's answers for 7 days unless `runFresh` is set. Platforms settle independently, so a `201` can contain both `SUCCEEDED` and `FAILED` rows — check each result's `status`. Requires `aivisibility.manage` |
| `GET /explorations?limit=20` | Exploration history for the project, newest first. Summaries only (no answers): id, prompt, region, platforms, who ran it and when |
| `GET /explorations/{explorationId}` | One exploration with every answer exactly as it was returned, including which platforms were served from cache. Re-executes nothing and re-pays nothing |
| `DELETE /explorations/{explorationId}` | Removes an exploration from the project's history. Other explorations that copied one of its answers are unaffected — they hold their own copy. Requires `aivisibility.manage` |
| `GET /runs/{runId}` | Single-run drill-down (answer, citations, mentions with sentiment / recommended / rank, and any `paidPlacements` the answer carried — each with `adUrl` (where the ad points), the advertiser's own `advertiserUrl` / `advertiserFaviconUrl` where the platform reports them, and `isRendered`: `false` means the platform served the ad but never displayed it, `null` means the platform does not report visibility) |

### Shared filters

Every analytics read accepts the **same filter set**, so a selection made in one panel means the same thing in all of them. For each filter, omitting it (or sending it empty) means *everything* — there is no `ALL` sentinel:

| Filter | Parameter | Notes |
|---|---|---|
| Platform | `provider` | Repeat to select several |
| Topic | `topicIds` | Repeat to select several; the literal `uncategorized` matches runs with no topic |
| Region | `regions` | `US` / `EU`; only meaningful once the project runs more than one |
| Date window | `preset`, `from`, `to` | A `preset` (e.g. `today`, `last_7_days`) takes precedence over a `from`/`to` pair (`YYYY-MM-DD`). Boundaries are resolved in the project's **reporting timezone**, set in project settings — requests do not carry one |

When a date window is given, jobs that finished inside it are aggregated instead of the last-`jobs` window. The dashboard sends presets directly and uses explicit dates for custom ranges and period-over-period comparisons.

The project-wide answer list (`GET /answers`) is narrowed by nothing but its filters, so it takes the whole shared set on top of its own four.

Row-listing reads scoped by a path id — `GET /jobs/{jobId}/runs`, `GET /prompts/{promptId}/runs`, and the org-wide `GET /ai-visibility/overview` — are already narrowed by that id, so of the shared set they take `regions` (and, on the per-prompt history, `provider`). This matters once more than one region is live: a job's run list and a prompt's fixed-size recent history otherwise interleave every region with no way to separate them.

New analysis fields on the responses above are nullable — `null` means the job predates the analysis pass (or it was disabled), never zero.

### Comparing against an earlier window {#comparison}

The reads listed below compare against an earlier window whenever they answer for a date range, and take the three comparison parameters shared with the rest of the analytics API — `comparePreset` (`previous_period`, `previous_week`, `previous_month`, `previous_quarter`, `previous_year`), or a custom `compareFrom`/`compareTo` pair. [Compare to an earlier period](/web-analytics#compare-periods) covers what each preset means, the one-year guard, and how `absoluteChange` / `percentageChange` read; the rest of this section is what is specific to AI visibility.

::: warning A comparison needs a date window
Without `preset` or `from`/`to`, these reads aggregate the **last `jobs` analyses** — a count, not a period — and there is no "the N jobs before those" to compare against. This is the one case where a report comes back with no comparison at all. Asking for one anyway is refused with `VAL_001` rather than answered without one, which would look like a report that honoured the request and simply found no change.
:::

| Read | What a comparison adds |
|---|---|
| `GET /visibility` | `comparisonSeries` — the same presence series over the earlier window's own jobs |
| `GET /provider-series` | `comparisonSeries`, split by platform the same way `points` is |
| `GET /breakdown` | Per platform: `previousRunCount`, `previousRunsWithBrand`, `previousPresenceRate`, `previousCitationCount`, `previousMentionRate`, `previousCitationRate`, `previousAvgAnswerRank` |
| `GET /competitors` | Per brand: `previousVisibilityRate`, `previousRank`, `previousShareOfVoice`, `previousCitationCount`, `previousAvgAnswerRank` |
| `GET /share-of-voice` | Per brand: `previousRunsWithBrand`, `previousShareOfVoice`, `previousRank` — one window-wide figure per brand, repeated on every point |
| `GET /topics-breakdown` | Per topic: `previousRunCount` and `previousPromptsWithRuns`, with each brand's own `previousVisibilityRate` and `previousShareOfVoice` inside the row |
| `GET /prompts-breakdown` | Per prompt × platform cell: `previousRunCount`, `previousRunsWithBrand`, `previousPresenceRate`, `previousAvgAnswerRank` |
| `GET /domains` | Per domain: `previousCitationCount` and `previousCitationShare` |
| `GET /citations/pages` | Per page: `previousCitationCount` and `previousCitationShare` |

Series reads (`/visibility`, `/provider-series`) return the earlier window as its **own jobs**, with their own ids and finish times — the two windows rarely run the same number of scans and no job here has a counterpart there, so line the two up by position rather than by date.

`/domains`, `/citations/pages`, `/breakdown`, `/competitors` and `/prompts-breakdown` also report **`comparisonJobsIncluded`** beside `jobsIncluded`. It is the field that tells the two zeros apart: `0` says the project ran no analysis in that window at all — which is why every previous figure is zero and every previous share is null — rather than having run and found nothing.

Rates and positions follow the convention the rest of the API uses. `previousRank` and `previousAvgAnswerRank` are **null, never a number**, when the brand was not measured then: reporting a missing brand as last place would read as a climb it never made, and 0 is the best answer position there is, not the absence of one. `absoluteChange` on a row ranked by a rate — presence, visibility, share of voice — is a **percentage-point** difference, so 0.4286 against 0.2857 reads as `14.3`.

Full request/response schemas are in the [API reference](/api-reference).

## Next steps

* [Bot & Crawler Detection](/crawler-detection) — see which AI crawlers visit your site (a separate dataset).
* [CLI](/cli) — run `kitbase ai-visibility` commands from the terminal or CI.
* [API reference](/api-reference) — full request/response schemas.

---

---
url: 'https://docs.kitbase.dev/site-audit.md'
description: >-
  Crawl any website, see what is wrong with it ranked by severity, and find out
  whether AI platforms can read it — in one report you can share with a link.
---

# Site Audit

Point Kitbase at a website and it answers one question: **what is wrong with it, and what should you fix first?**

An audit crawls the pages, checks each one, and returns a single report — a score, a ranked issue list, and the table of every page it reached. The crawl and its rule checks are ours, so that part costs nothing per run beyond time and you can run it as often as you like.

Three of the checks are not ours to give away, and you can turn each of them off before a run:

| Check | What it spends |
|---|---|
| [**AI page reads**](#page-detail) | AI credits — a model reads your pages |
| [**Duplicate detection**](#duplication) | AI credits — an embeddings model reads your pages |
| [**Page speed (Lighthouse)**](#performance) | The same data credits as your other paid SEO data |

If your organization is out of credits, the audit still runs and the parts it could not buy come back empty, rather than the whole audit failing.

::: info What makes this different from a generic SEO crawler
Broken links and missing meta descriptions are a solved commodity. The part worth your attention is the **AI-readiness score** — whether an AI platform can reach, parse and cite your pages. That is the headline of the report; the issue list is what makes it trustworthy.
:::

## Running an audit

Press **Run audit** on the Site Audit page. The dialog asks two things: which website, and which checks to spend on it. One audit runs at a time per project.

A run starts from the homepage and the sitemap, then follows internal links outward until it reaches its page limit. It respects `robots.txt` for our user agent, skips assets that are not pages, and holds itself to a polite request rate.

| Option | Default | What it does |
|---|---|---|
| **Website** | Your project's website | Any address to audit. See [Auditing any website](#auditing-any-website). |
| **Page limit** | 100 | How many pages the crawl may fetch. Higher means longer, not more expensive. |
| **Follow links** | On | Off crawls only what the sitemap lists — faster, and blind to anything unlisted. |

While it runs you see the phase, the page counts, and the URLs it is crawling right now. **Cancel** stops it; everything already crawled keeps its results.

### Auditing any website

The **Website** field is prefilled with your project's own site, and leaving it alone is the normal case. Type any other address and the run audits that instead — a competitor, a client's site, a site you are about to acquire. The address is reduced to its domain, so a path or a query is discarded; IP literals, ports and credentials are rejected.

::: warning Audits of other websites have a daily allowance
Ten a day per project. The eleventh is refused with a message saying so, and the counter resets at midnight. Audits of your project's own site are unlimited and never touch the allowance.
:::

Two checks are about *your* project rather than about a website, so they cannot run against somebody else's:

* **Traffic & AI visibility** grades AI-crawler visits, crawl freshness and share of voice from your own analytics.
* **Plan compliance** checks a site against your project's approved plan — the addresses, figures and terms you signed off on.

They are skipped on an external run, and the report says they were skipped rather than reporting them as failures.

The rest of Kitbase only ever reads audits of your project's own site. A run pointed at a competitor cannot answer for you — it does not feed recommendations, the assistant, or a workflow.

### Choosing which checks run

The dialog lists every check this server can run, each pre-ticked. Untick the ones you do not want and the run does less work; the list is served by the API, so a check added in a later release shows up on its own.

| Check | What it does | Can you turn it off? |
|---|---|---|
| **Robots & AI crawler access** | Reads `robots.txt` and grades whether search and AI crawlers are allowed in | No |
| **llms.txt** | Looks for an `llms.txt` file describing the site to AI assistants | No |
| **Sitemap discovery** | Finds and walks the sitemap to discover the site's pages | No |
| **Homepage & HTTPS health** | Loads the homepage and follows its redirect chain | No |
| **Page crawl** | Fetches the site's pages, following links up to the page limit | No |
| **Edge blocking probe** | Sends requests with real AI-bot signatures to detect firewall or CDN blocking | Yes |
| **Traffic & AI visibility** | Grades AI-crawler visits, crawl freshness and share of voice from your analytics | Yes — own site only |
| **Page quality checks** | Grades every crawled page: titles, headings, structure, AI-readability signals | Yes |
| **Facts & consistency** | Cross-checks stated facts, figures and taxonomy for contradictions across pages — this is what fills the [Checklist](#checklist) tab | Yes |
| **Plan compliance** | Checks the site against your approved plan's addresses, figures and terms | Yes — own site only |
| **AI page reads** | An AI reads key pages and reports how each one positions itself — **spends AI credits** | Yes |
| **Duplicate detection** | Embeds page content and clusters near-duplicate pages — **spends AI credits** | Yes |
| **Page speed (Lighthouse)** | Measures performance, SEO and accessibility on a sample of pages — **spends data credits** | Yes |

The five core crawl steps always run — without them there is no audit to report on.

A check you untick appears in the report as **not applicable** rather than vanishing, and it is left out of the score's numerator *and* its denominator. A narrower audit is not a worse-scoring one.

A check this server cannot run at all — no measurement provider configured, no AI model available — is shown disabled with the reason next to it, rather than offered and then quietly skipped.

## The report

Six tabs: **Issues**, **Pages**, **Performance**, **Duplication**, **Checklist** and **Scorecard**.

### Score

The AI-readiness score (0–100) and its three category scores: **Crawler access**, **Machine readability** and **Analytics**. This is the weighted verdict of the 16-item scorecard — a check that passes still counts, which is why the [Scorecard](#scorecard) keeps its own tab.

### Tiles

Pages crawled, issues found by severity, average response time, and how many pages came back blocked, broken or erroring.

When a Performance measurement ran, four more tiles join them: Lighthouse tests, average performance, average SEO and average accessibility. If nothing was measured the four are hidden rather than shown empty — no measurement and a bad measurement must not look the same.

### Issues

Every problem the audit found, grouped by severity and then by rule. Expanding a rule explains why it matters, what to do about it, and which pages it affects.

| Severity | Means |
|---|---|
| **Critical** | Costs traffic or indexing outright — unreachable, unreadable, or blocked. |
| **Warning** | Real damage, but the page still works. |
| **Info** | Worth knowing, not worth interrupting anything for. |

Rules come from several places, and each row is chipped with which:

* **Crawl** — what only a crawl can answer: blocked pages, server errors, broken pages, redirect chains and loops, duplicate meta descriptions, canonical conflicts, slow pages, buried pages.
* **Scorecard** — a scorecard item that did not hold up. A failure on a heavily-weighted check (AI crawlers blocked at the root) is critical; a light one (no `llms.txt`) is not.
* **Page checks** — the per-page content checklist: what one page's title, headings, structure and copy get wrong.
* **Consistency** — relational findings computed over the whole crawl: links pointing at pages that turned out to be broken, pages nothing links to, pages publishing identical copy, and figures that contradict each other between pages.
* **Content** — where a page departs from your project's approved plan.

A source you have no permission to see contributes nothing, and the counts are computed after that filter — so a hidden producer cannot be inferred from a total that does not add up.

::: warning Orphan pages need a complete crawl
"Nothing links here" is a claim about everything, so it is only reported when the run followed links, read your whole sitemap, and did not stop at its page limit. A partial crawl says nothing about orphans rather than guessing.
:::

### Pages

Every page the crawl reached, with its status, title, H1 count, word count, images missing alt text, response time, crawl depth and issue count. Filter by status, search by URL, and sort by slowest, thinnest or deepest.

This is **one run's snapshot**. Every page number in Kitbase — here, in the assistant's answers, in a workflow that walks your pages — comes from the latest completed audit of your own site, so two figures read at the same moment were measured by the same crawl.

### Page detail

Click a row to open one page in full:

* **What the crawl measured** — status, response time, words, headings, H1 count, images and how many lack alt text, internal and external links, crawl depth, whether it is in the sitemap, whether it is indexable, its canonical and its meta description.
* **Page checks** — which rules this page failed, what each one found, and how to fix it.
* **How a model read this page** — present when the run included **AI page reads**: the question the page answers, what it says it is, how it sits against the rest of the site, and what to change.
* **Nearest pages by meaning** — the pages closest to this one, best first, from the same embeddings that build the [Duplication](#duplication) tab.

**First seen** and **Last changed** are carried forward between audits of your own site, so they predate this run: a page first crawled in March still says March. A page with no earlier snapshot to carry from shows neither.

The markup the crawl retained is deliberately not shown. It is an input to the checks, not a report.

### Performance

What your pages cost to load, measured with **Lighthouse**: performance, accessibility, SEO and best-practices scores, plus LCP, CLS, TBT and TTFB. Filter by device or score band, show only the runs that failed, and sort by worst score or slowest metric. **View issues** opens what Lighthouse actually objected to on that page.

Four things are worth knowing about this tab.

**It measures a sample, not the whole crawl.** Each measurement is a paid call to a measurement provider, so a run measures your most important pages — the homepage first, then the pages closest to it — rather than every page it crawled. The tab says how many it measured.

**It runs after the crawl, not during it.** The measurement is a separate job that starts once the crawl finishes, so the rest of your report is readable while this tab is still filling in. The report header says *Page speed still measuring* and the tab shows *Measuring the sampled pages* while it runs — results land here on their own within a few minutes, so an empty table right after the crawl means "still measuring", never "nothing was measured".

**It spends.** Measurements draw on the same data credits as your other paid SEO data. If your organisation is already at its monthly limit, the audit still runs and this tab stays empty rather than the whole audit failing.

**It can be absent entirely.** The measurement provider is DataForSEO. Self-hosters must set `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD` — the same account that powers [AI Visibility](/ai-visibility)'s Google surfaces, [Backlinks](/backlinks) and [keyword research](/keyword-research). Without them the Performance tab stays empty and every other part of the audit works as normal; the tab says so instead of showing a blank table.

::: info Why there is no INP column
INP is a *field* metric — it needs real visitors interacting with the page. A Lighthouse run is a lab test on one synthetic load, so it cannot produce one. **TBT** (Total Blocking Time) is the lab stand-in and is what the tab reports. Labelling TBT as INP would be claiming a measurement nobody made.
:::

A page that could not be measured keeps its row and is marked *Could not be measured*, so a page your server refused to serve is visible rather than silently missing.

### Duplication

Which of your pages say the same thing. The run embeds each page's copy and groups the pages that land near each other — **grouped, not paired**: three pages that each duplicate the next are one problem with three pages in it, and reporting them as pairs would triple the apparent count.

Each group carries its tightest link as a percentage and one of two verdicts:

| Verdict | Means |
|---|---|
| **Near-duplicate** | Two pages that are nearly the same page. Worth merging, redirecting, or differentiating. |
| **Related** | Normal for a site that covers one subject. Reported so you can see what the grouping is made of rather than only being shown the alarming half. |

Like page speed, the comparison runs after the crawl — the tab says *Comparing pages now* and fills in on its own a few minutes later, rather than showing an empty list that reads as "no duplicates".

Reading this tab costs nothing — the vectors were bought once, when the run embedded the pages, and grouping them is free from then on. The tab says so plainly when the run had no embeddings model available or could not afford the pass.

### Checklist

Every site-wide check the run graded, **including the ones that hold up** — the facts and figures your pages state, and whether they agree with each other. The issue list can only ever tell you what is wrong; this is the only place that can say "seventeen checks ran and fifteen hold up", which is what turns an accusation into a measurement.

Filter by **All**, **Problems** or **Holding up**. Each row explains what the check is, what this run measured, how to fix it, and which pages it names — empty when the finding is a count or a comparison rather than a set of pages.

### Scorecard

The 16-item AI-readiness checklist behind the [score](#score), including the items that passed. Any single check can be re-run on its own with **Re-check** without starting a new audit.

Checks you left out of the run appear here as not applicable, so a shorter run is legible as a shorter run.

## Export

**Export** hands you the Issues, Pages or Performance tab as CSV or JSON, filtered exactly as the screen is.

**Report (PDF)** is the whole report as one document: the score and its three category scores, the run's stats, any notice about what the crawl did not cover, and the full issue list — every rule with its description and its fix, whichever tab you happened to be on. It opens your browser's print dialog, where **Save as PDF** is the destination, so the file carries selectable text and live links rather than a picture of the screen. The affected URLs stay in the app: one bad template can put thousands of them under a single rule, so the PDF prints how many pages each rule hit and leaves the list where you can filter it.

## Sharing a report

**Share** on a finished audit mints one public link. Anyone holding it can open the report without a Kitbase account.

The token in the URL **is** the credential — there is no second check behind it. Treat the link the way you would treat the report itself.

| | |
|---|---|
| **What the reader sees** | The domain, the dates, the AI-readiness score and its three category scores, the graded scorecard with the sentence explaining each verdict, the ranked issue list, and the page table cut down to URL, status, title, word count and response time. |
| **What never travels with it** | Your organization and project, who shared it, the AI page reads, the retained page content, and the evidence behind the analytics checks — that evidence is your own traffic and AI-visibility data. Analytics checks keep their verdict and its sentence, and lose their workings. |

The redaction happens on the server, so there is nothing sensitive in the response for a reader to dig out.

Pressing **Share** twice hands out the same link — two people sharing one report cannot end up distributing two different URLs. Only a completed audit can be shared; a run still crawling has no report to hand anybody.

**Turn off this link** revokes it. The link stops working immediately and answers "not available", indistinguishable from a token that never existed. Sharing again mints a *new* link rather than reviving the old one, so a link you have revoked stays revoked.

## Reviewing an article before it is published

An audit reads a crawl, so the earliest it can see a new article is after it is live. **Review a draft**, the second tab of Website Scan, takes the file instead: drop a markdown or HTML file on the panel or paste the text, and the same checks that grade a published page grade the draft — plus the one only a pre-publish review can make, whether it contradicts something the site already says.

That last part is why the timing matters. A wrong figure is quotable the moment it publishes, and the next crawl finds it only after an answer engine has already lifted it.

Front matter is read for the title and description, so an ordinary blog file needs nothing else filled in. **Where it will publish** is optional and worth giving when you know it: it lets the review check the draft against the page already at that address.

The verdict answers one question. **This contradicts what your site already says** is reserved for exactly that — a figure, a structure count or a title the site has already committed to differently. A thin description or a missing opening answer comes back as something to fix, not as a contradiction. Under it, every check is listed with what it measured and what to do about it, passes included, because "two of fourteen" and "two of two" are different pieces.

What it grades depends on what you send. A markdown file is the prose you own — opening answer, question headings, statistics, heading order, lists, length, title, description, image alt text. Structured data, social tags and the byline belong to the template that renders it, so they are only asked of an HTML draft, which is the whole page.

**Nothing is stored.** The draft is graded and forgotten: no audit row, no findings, no copy of the text, which is why there is no history of past reviews to open. Everything a live URL is needed for — status, canonical, sitemap membership, AI-crawler access, citations — still waits for an audit, and the review names what it left out rather than passing a draft as fully checked.

The comparison needs a completed audit of your own website. Without one the prose checks still run and the page says so.

Your coding agent can run the same review on a file without opening the dashboard — see [`audit_draft`](/sdks/mcp#reviewing-a-draft-before-you-publish) on the MCP server.

## Audit history

The Site Audit page lists every audit the project has run, newest first, with the site it audited, its status, its score, when it started and how long it took. Open any one of them to read that run's full report, or delete it from the row menu — deleting one audit takes its checks, pages, findings and measurements with it and leaves the others alone.

An audit that is still running cannot be deleted. Cancel it first, so that stopping a run and discarding it stay two decisions rather than one button that quietly does both.

## When something is blocked

If bot protection turns our crawler away, the report says so plainly rather than reporting hundreds of phantom broken pages. Allowlist the user agent to fix it:

```
Mozilla/5.0 (compatible; KitbaseAuditBot/1.0; +https://kitbase.dev/audit-bot)
```

Every AI crawler meets the same wall you put in front of ours, so this is worth fixing for its own sake. See [Bot & Crawler Detection](/crawler-detection) for what our crawler does and how to recognise it.

## Older audits

Audits run before this release keep their score and scorecard but have no issue list or page table — they were sampled, not crawled. Audits older than the tab that reads them have nothing in it either: no measurements before Performance existed, no groups before Duplication, no graded checklist before Checklist. The report names that rather than showing an empty list. Run a new audit for the full report.

---

---
url: 'https://docs.kitbase.dev/backlinks.md'
description: >-
  Detect new backlinks from real referral traffic, recover links pointing at
  dead pages, and find the domains AI platforms cite so you know where to earn
  links.
---

# Backlinks

No tool can *create* backlinks for you — they're earned on other people's sites. What Kitbase does is find the ones that matter and tell you where to earn more, using data you're already collecting. It's arranged as the three questions you actually ask, in order:

* **Overview** — how am I doing? The headline figures, a year of growth, the pages doing the work, and a text box for looking up *any* domain: yours, a competitor's, or a site you're about to pay for a placement on.
* **Opportunities** — what should I do next? Domains linking to your competitors but not to you, links you've already earned that send no traffic, links you've lost, dead pages still receiving links, and the third-party sites AI platforms cite in your category.
* **All links** — who links to me? Every referring domain and every exact linking page Kitbase holds for your site.

::: info Built from data you already have
Most of Opportunities needs nothing new: reclamation reads your existing [web analytics](/web-analytics) referrers, and the AI-cited list reads your [AI Visibility](/ai-visibility) citations. Only a profile pull calls a paid external index — and only when you press the button.
:::

## Overview

Overview opens on your own site and carries one text box. Type a domain and confirm the pull, and Kitbase buys that domain's link profile and keeps it: totals and authority, its strongest referring domains, a sample of the individual links, and a year of monthly history.

**Looking things up again is free.** Every domain you've pulled is listed under **Previous lookups**; opening one reads what you already bought and never spends again. Sorting, filtering, searching and paging within a stored report are all free too — they're queries over rows on your side.

**Whole site or exact page.** A bare domain (`example.com`) is read as the whole site; anything with a path (`example.com/pricing`) as a single page. Kitbase infers which you meant from what you type, and the toggle overrides it. Page-scope targets have no growth history — the index reports a domain's history, not one URL's — so those charts are hidden rather than shown empty.

### What a profile shows

| Section | Where | What it tells you |
|---|---|---|
| **Headline figures** | Overview | Three numbers, not a wall of them: **sites linking to you** (and across how many links), **how many of those ever sent a real visitor**, and **site authority** — scored 0–1000 and labelled, from "Just getting started" to "Very strong". A blank figure means the index didn't report it — never zero. |
| **Growth** | Overview | Backlinks and referring domains month by month for the last year, so you can see whether a profile is compounding or decaying, plus new versus lost links per month. A profile that grows while losing heavily is a different story from one that simply grows. |
| **Linked pages** | Overview | Which of the target's pages attract the most links, grouped from the link rows Kitbase holds. |
| **Referring domains** | All links | Who links to the target, strongest first, with authority, spam score, link counts and the date the index last saw the link. |
| **Backlinks** | All links | The exact linking pages: the page each link lives on, the page it points at, its anchor text, whether it's dofollow, its rank and spam score. |

**Your own site shows more.** Visits, top landing page, the **Untapped** and **Lost** filters and the ignore/restore controls all come from your first-party analytics, which exist for your site and for nobody else's. On a researched competitor those columns are absent rather than empty — the honest answer, since no backlink index can tell you who clicked. The **All links** tab is always about your own site for the same reason.

::: warning Linked-page counts are a floor, not a total
Linked pages is grouped from the link rows Kitbase has stored, not bought from a separate index endpoint. That's the bounded sample plus any pages you've explicitly acquired — so treat the counts as "at least this many", never as a page's true total.
:::

## Sources

Every visit your SDK records carries the page that sent it (the *referrer*). When a domain sends its first visit, that's almost always a new link that just went live. Kitbase watches for those and lists each referring domain with the traffic it actually drives — something a backlink index alone can't tell you.

Search engines, social networks, AI assistants, and your own domain are excluded automatically, so the list is genuine third-party links, not noise. A domain you don't care about can be dismissed with **Ignore**; restore it any time.

**A new-backlink notification** is sent (in-app, and to any [webhook](/api-reference) subscribed to `backlink_detected`) the first time a *recent* backlink is detected. When the feature first runs for a project with existing history, all of that history is loaded silently — you're only notified about links that appear from then on, not flooded with old ones.

::: warning What referrer detection can and can't see
This finds backlinks that **send traffic** — the ones worth knowing about. A link that exists but nobody clicks won't appear, and browsers often trim the referrer to just the domain (so the exact linking URL isn't always available). It complements a full backlink index; it doesn't replace one.
:::

### Fields

| Field | Meaning |
|---|---|
| **Domain** | The referring host, normalized (lowercased, `www.` stripped). Subdomains are kept distinct — `news.example.com` ≠ `blog.example.com`. |
| **Sessions** | Visits this domain referred within the selected window. |
| **First seen** | The earliest visit ever referred by this domain (historical — not when Kitbase noticed it). |
| **Top landing page** | The page most of its referred visitors arrive on. |
| **Source URL** | A captured referring URL — the actual linking page, when the browser sent the full referrer. |
| **Domain rank** | Authority score (0–1000) of the referring domain. Blank until a [link graph](#link-graph) pull has run, or if the domain falls outside the stored top domains. |
| **Spam score** | DataForSEO's spam signal for this domain's links (0–100, higher is spammier). Same blank rule as Domain rank. Domains at or above the spam threshold (30 by default) are dropped during a pull, so a populated value is always below it. |
| **Backlinks** | How many links this domain points at your site, per the link graph. Same blank rule as above. |
| **Lost** | The date the link graph reported the link gone. Blank means it's still linking, or that the domain isn't in the graph at all. The **Lost** filter lists these — including links that never sent traffic. |
| **stale** | A marker beside the domain, meaning the most recent pull didn't return it — its rank and backlink counts are left over from an earlier one. Hover for the date they were last confirmed. |
| **synced** | A marker beside the domain, meaning the [link graph](#link-graph) also knows it. Rows with visits come from your own analytics either way — deleting synced data clears the index columns, never the traffic history. Click any row for the domain's detail, including the exact linking pages the index stores. |

The list mixes two origins on purpose: domains seen in **your own traffic**, and domains known only to the **synced link index** (the **Untapped** and **Lost** filters, plus part of **All**). Index-only rows have no visit history and nothing to ignore or restore — they exist because the index saw a link, not because anyone clicked it.

**Stale is not the same as Lost.** A pull stores only your top domains by authority, so a domain slips out of that slice simply by being outranked as your profile grows — which is not evidence the link disappeared. Kitbase marks those rows stale rather than reporting them lost, and only calls a link lost when the index says so.

## Reclamation

The highest-ROI backlink work is often a link you already have: when an external site links to a page of yours that now returns an error, that link's value is leaking. Reclamation finds those pages — externally referred visitors landing on URLs your [site audit](/site-audit) recorded as broken (any non-2xx status) — so you can add a redirect and recover the link without any outreach.

Each row shows the dead path, its HTTP status, the referring domains still sending traffic to it, and how many sessions are affected. Fix it by pointing the old URL at the right page (a 301 redirect).

::: info Requires a completed site audit
Reclamation matches referred traffic against the pages your last crawl reached, so the project needs a completed [site audit](/site-audit) of its own website first. If none has run, the page tells you — run one and reclamation lights up. Pages that were never in your sitemap can't be checked this way.
:::

## AI opportunities

When someone asks an AI platform "what's the best tool for X?", the platform cites its sources. The sources it cites for **your** category — where **you're not mentioned** — are exactly the sites worth earning a link or listing from: getting cited there improves both traditional SEO and your [AI Visibility](/ai-visibility).

Kitbase aggregates the third-party (non-you, non-competitor) domains cited across your AI Visibility prompts and ranks them by how often they appear in answers where your brand is **absent** — the biggest gaps first.

| Field | Meaning |
|---|---|
| **Domain** | A third-party site AI platforms cite for your prompts. |
| **Type** | What kind of source it is (review site, community, news, docs, …). |
| **Citations** | How often it was cited across the aggregated analyses. |
| **Gap prompts** | Prompts where you're absent but this domain is cited — the priority signal. |
| **Already linking** | Whether this domain also shows up as one of your detected backlink sources. |

The table starts with the 25 most-cited domains, and the line above it says how many cited domains were found in total — **Show more** raises the cap in steps up to 200, the most this view will list.

On Kitbase Cloud, opportunities that are purchasable as guest-post placements show a price and deep-link into the [Link Marketplace](/link-marketplace), where the same citation signals rank the catalog.

::: info Depends on AI Visibility
This view reads your AI Visibility citation history — set up brands and prompts there first. No extra analysis runs and no extra cost.
:::

## Link graph

Referrer detection only ever finds links that **send traffic**. Most links don't. The link graph fills that half in from an external backlink index, and it's the one part of Backlinks that costs money to run.

A pull fetches several things from the index:

* **Profile summary** — how many referring domains and inbound links you have in total, how many are dofollow, and your domain's authority rank. Shown against how many of those domains actually sent you a visitor, which is usually a much smaller number and the point of the whole view.
* **Exact links** — the individual linking pages behind the profile. Click any domain under **All links** to see the exact links the index knows from it: the page each link lives on, the page of yours it points at, its anchor text, whether it's dofollow, and its link rank. When a link's target matches a landing page real visitors from that domain arrived on, it's marked **likely entry** — the cross-reference between what the index says exists and what your traffic says happened. This is a bounded snapshot — the top links by rank, one per referring domain and anchor (so a sitewide footer link counts once, not a thousand times), and only links the index currently sees as live.
* **Untapped links** — the **Untapped** filter under **All links** shows domains whose links have never sent a single visitor, highest authority first. These are links you've already earned but that aren't working for you yet — click one to see exactly which pages the links live on.
* **Lost links** — domains the index no longer sees linking to you. **Opportunities** lists them, and the **Lost** filter under **All links** shows them in place. This filter reads the link graph rather than your traffic, so it includes links that disappeared without ever sending you a click — usually the majority, and the ones a referrer-only view can't see at all. Those rows have no first-seen date and no **Ignore** action, because there's no traffic record behind them.
* **Competitor gap** — domains that link to at least one of your tracked competitors but not to you, ranked by how many competitors they link to and then by authority. It is **derived from the competitor profiles you have pulled**, not bought separately, so it costs nothing to look at and updates the moment you pull another competitor. Only genuine outreach targets count: the gap keeps dofollow links and drops near-zero-authority domains, so it stays a ready-made outreach list rather than a dump. Filter it by a single competitor to see only the sites backing that one rival.

  A competitor whose profile you have never pulled contributes nothing to the gap, and the page names those explicitly — pull one to widen the list. The gap is dated by the **oldest** profile behind it, because that is how current it actually is.

**Lost is not the same as Ignore.** Dismissing a source is your judgment about whether it matters; lost is the index's statement about whether the link still exists. They're independent, so a source you ignored months ago still shows up under **Lost** when its link disappears.

::: info Low-quality links are filtered out
A raw backlink index carries a lot of junk. Kitbase drops referring domains and exact links whose spam score is 30 or higher before storing them, and the competitor gap keeps only followed, direct links from domains above a minimum authority rank — so what you see is the part worth acting on, not link-farm noise. The **spam score** (0–100, higher is spammier) is shown on each competitor-gap row. Self-hosters can tune or disable both thresholds with the `linkgraph.data-for-seo.max-spam-score` and `backlinks.competitor-gap.min-domain-rank` settings — set either to `0` to turn that filter off.
:::

### When it pulls

**Only when you ask.** Nothing here refreshes on a schedule, on Cloud or self-hosted: a pull happens because a person pressed the button, which is what makes the cost predictable. Plans set a daily limit on how many pulls an organization can start; pulls you have already stored stay readable regardless, and the limit resets at midnight UTC.

Your own domain is resolved on the server from your project settings, so pulling your own profile needs nothing typed. You can also pull a **competitor's** profile deliberately — that is what feeds the competitor gap — and each one is a separate authorized pull rather than something that happens quietly in the background.

Every confirmation names two figures in credits: what the pull is **expected** to draw, and the **ceiling** it cannot exceed. The ceiling is higher because a worker that crashes after the index has already billed a successful response is allowed exactly one replay — so the ceiling is the real worst case, not the routine bill.

**Asking twice doesn't pay twice.** A request identical to one that already completed answers with what it stored rather than buying it again; a genuine refresh takes a second, explicit confirmation. Ordinary retries and double-clicks can't trigger one.

### Going deeper than the sample

A profile pull stores a bounded sample — the top links by rank, one per referring domain and anchor. Two actions buy beyond it, and both are explicit:

* **All links** loads the next page of *every* link, ungrouped, rather than one per anchor. Each page is a separate confirmation, and paging continues from where the last one stopped.
* **Pull more** on a referring domain buys every link from that one domain. The links already stored for it show for free first; this only buys what the sample left out.

Rows either action brings back are kept permanently and survive later profile refreshes — you paid for them specifically, so a routine refresh never sweeps them away.

::: warning Costs money and needs setup
The link graph is powered by DataForSEO. Self-hosters must set `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD`; without them the tab tells you it's unconfigured and the rest of Backlinks works as normal. Each pull spends credits from your plan's monthly allowance — the same pot that covers AI Visibility and keyword research. A pull that runs out of credits, or hits a provider rate limit, resumes where it stopped rather than re-paying for calls that already succeeded.
:::

### Deleting synced data

To clear everything a pull has stored — the profile totals, the referring domains and the exact **Links** — use **Delete synced backlinks** under **Project settings → Maintenance**. Your traffic-detected Sources are first-party data and are left untouched: a domain that both linked to you and sent you a visitor keeps its row and loses only what the provider added. The competitor gap empties with the profiles it is derived from. The data comes back on your next pull. The delete is blocked while a pull is running — wait for it to finish and try again. It needs the `backlinks.manage` permission.

## Permissions

Backlinks is gated by two permissions: `backlinks.view` (see every view, including the link graph) and `backlinks.manage` (dismiss or restore sources, start a link-graph refresh, and delete synced data). Owners, admins, and developers get both; analysts get view-only.

## From the CLI

Every view is available over the [CLI](/cli) for scripts and CI:

```bash
kitbase backlinks list --project <id>            # detected sources
kitbase backlinks detail --domain example.com    # drill into one source
kitbase backlinks reclamation                    # dead pages with inbound links
kitbase backlinks opportunities                  # AI-cited domains to target
kitbase backlinks update <id> --status ignored   # dismiss a source
```

## Next steps

* [Web Analytics](/web-analytics) — the referrer data behind Sources and Reclamation.
* [AI Visibility](/ai-visibility) — the citation data behind AI opportunities.
* [API reference](/api-reference) — the REST endpoints behind every view.

---

---
url: 'https://docs.kitbase.dev/link-marketplace.md'
description: >-
  Buy guest-post placements on the sites AI platforms already cite for your
  prompts, with transparent pricing and a 3-month link guarantee.
---

# Link Marketplace

The [Backlinks](/backlinks) AI-opportunities list tells you *where* a link would move your AI visibility. The marketplace closes the loop: many of those domains are purchasable as guest-post placements, directly from the same page.

The catalog carries tens of thousands of vetted sites. What makes it different from a generic guest-post store is the enrichment: for your project, every site that AI platforms cited when answering your tracked prompts is flagged with its citation count and — the strongest signal — how often it was cited in prompts where your brand never appeared. Those are the sites already shaping the answers you're trying to enter.

::: info Cloud only
Ordering runs through Kitbase's marketplace account and payment processing, so the marketplace is available on Kitbase Cloud, not in self-hosted installs.
:::

## Where it lives

The **Backlinks → Opportunities** tab has two sides. **Targets** is the AI-cited-domain worklist — every third-party domain AI platforms cite for your prompts, ranked by where your brand is absent; domains carried by the marketplace show a **Buy** button, the rest remain manual-outreach targets. **Catalog** is the full purchasable store below. (On self-hosted installs without the marketplace configured, only Targets shows.)

## Browsing the catalog

The **Catalog** view lists purchasable sites with the metrics that matter for link building:

| Column | Meaning |
|---|---|
| Cited | How often AI platforms cited this domain for your prompts, and in how many *gap prompts* (where your brand was absent) |
| DA | Moz Domain Authority (1–100) |
| Traffic | Monthly visitors reported for the site |
| Speed | Typical days from order to publication |
| From | Retail price of the cheapest placement format |

Filters cover domain, country, topic category, site type, link type (dofollow/nofollow), minimum DA and traffic, price range, placement speed, and "publisher writes" availability. The default sort puts cited domains first — gap-prompt count, then citation count.

Sites flagged with sensitive categories (gambling, forex, …) show a notice on their detail view; some publishers charge a surcharge for sensitive topics, which is included in the price you see.

## Ordering a placement

1. Pick a site and a placement format. Each format shows its price, link type, and the maximum number of links allowed in the article.
2. Choose who writes it:
   * **You provide the article** — title and full HTML body, at least 2,000 characters (excluding spaces), at most 3 external links.
   * **The publisher writes it** — available where the site offers writing; you provide a brief and the writing fee is folded into the total.
3. Add your **anchors**: the anchor text and target URL for each link you need placed (up to the format's link limit).
4. Review the total and pay. Payment is a one-off card charge (Stripe Checkout); the price you confirm is validated against the marketplace at that moment, so a stale listed price can never be charged — if the publisher changed their price you're asked to re-confirm.

Unpaid orders expire after 24 hours.

### Order lifecycle

| Status | Meaning |
|---|---|
| Awaiting payment | Checkout open; cancel any time |
| Being placed | Paid — our team is placing the order with the publisher |
| With publisher | Publisher has ~72h to accept |
| In progress | Accepted; writing or moderation underway |
| Changes requested | The publisher asked for edits — update your article in the order and we relay it |
| Published | Live, with the article URL; the 3-month guarantee starts |
| Completed | Guarantee window elapsed with the link intact |
| Declined / Refunded | Publisher declined — your payment is refunded automatically in full |

You're notified in-app (and by email for the moments that need you: published, changes requested, declined) as the order moves.

## The 3-month link guarantee

Every placement includes link-deletion protection for 3 months from publication:

* Kitbase checks each published article regularly and verifies your links are still present.
* A temporarily unreachable site never counts against the guarantee — only repeated, conclusive failures do.
* If your link disappears, we first pursue restoration with the publisher. If it can't be restored, you receive a full refund.

The order detail shows the guarantee end date and the result of the most recent link check.

## Permissions

| Permission | Grants |
|---|---|
| `marketplace.view` | Browse the catalog and view orders (all roles) |
| `marketplace.order` | Place, cancel and edit orders — spends real money (owner and admin only by default) |

---

---
url: 'https://docs.kitbase.dev/keyword-research.md'
description: >-
  Find what your audience searches for, with monthly volume, ranking difficulty,
  cost-per-click and intent — then save the keywords that matter to your project
  and watch them over time.
---

# Keyword Research

Every other part of Kitbase looks backwards: analytics says what happened, site audit says what's broken, backlinks says who links to you. Keyword research answers the question a content team actually starts its week with — **what should we write about, and is it worth it?**

You type a topic, pick a market, and get back related keywords with their monthly search volume, ranking difficulty, cost-per-click and search intent. The ones worth pursuing get saved to the project, where they sit alongside the rankings and AI citations you already track.

::: warning This feature spends credits per use
Unlike the rest of Kitbase, every search here buys data from an external provider — roughly **3–9 credits per search**, and about **70 credits** to refresh 5,000 saved keywords. The cost of what you're about to do is shown before you run it, cached results are free, and everything is metered against your plan's monthly credits.
:::

## Researching a topic

The Research tab opens on a single centred search box. Enter one seed topic — "event lead capture", "crm for nonprofits" — pick the market, and search. Once results arrive the same controls compress into a strip above the table, so the next search is one edit away.

**Mode** decides where the ideas come from:

| Mode | What it returns |
|---|---|
| **Auto** (default) | Tries related keywords, then suggestions, then broad ideas, stopping as soon as it finds enough. Costs one to three provider calls. |
| **Related** | Keywords the provider considers semantically adjacent to the seed. |
| **Suggestions** | Longer phrases that contain the seed — the long tail. |
| **Ideas** | The broadest set: everything topically connected. |

Auto is the right default and the reason the price is quoted as a range: a rich seed answers on the first call, a thin one walks all three before giving up.

**Result limit** (150 / 300 / 500) is a price knob as well as a display one — the provider bills per row returned.

**Clickstream volumes** is an optional toggle that buys search volumes refined with real clickstream data instead of the standard estimates. It **doubles** the price of the call, so it's off by default and labelled with what it costs.

### Reading the results

| Column | What it means |
|---|---|
| **Volume** | Average monthly searches in the selected market. |
| **CPC** | What advertisers pay per click — the clearest signal of commercial value. |
| **Competition** | How contested the keyword is in paid search, 0–1. |
| **Difficulty** | How hard it is to rank organically, 0–100. |
| **Intent** | Informational, commercial, transactional or navigational. |

Competition and difficulty are colour-banded on the same scale — green is winnable, amber and orange are contested, red is not worth starting — so a 500-row table can be scanned for the openings before any number is read. Hovering a banded value names the band. Intent is coloured by category rather than by rank: transactional green, commercial violet, informational blue, with brand-seeking navigational searches left neutral.

A dash means the provider doesn't measure that value for this market — **not** that the value is zero. That distinction matters in Google-Ads-served countries (see [Markets](#markets)), where difficulty and intent are never available.

### Cached answers

Search results are cached for 24 hours and shared across the whole install, because search volume is public data — the same number for every Kitbase customer who asks. When you see a result marked as cached, it cost nothing, and the age of the answer is shown so you know what you're looking at.

### Recent searches

A result lives on the page you ran it from — reload, and the table is gone. The **Recent searches** tab is how you get back to it: a paged table of what this project has already searched for, newest first, with the market, source, how many keywords came back and who ran it.

Each row opens its own page, at its own URL, so a past search can be linked to — and **opening one is always free**. The keywords a search returned are stored for **30 days** and read straight back from Kitbase; nothing is re-run, nothing reaches the provider, and the page cannot spend your credits. That also means anyone with `keywords.view` can read a search a colleague ran, without needing permission to spend.

A row marked **Free to re-run** is about the other thing: whether *running the search again* would cost anything. Fresh results are cached for 24 hours, so a search run this morning re-runs for nothing — including one a colleague paid for — while last week's is bought again at the usual price, which the estimate above the search bar shows before you commit.

Past 30 days the stored answer is deleted. Its page then says so and offers to run the search again, which is the one moment on that screen where credits are in question.

The Research tab is left alone throughout: it keeps showing the search you ran there, across tab switches, until **New search** clears it.

Running the same search twice does not add a second entry; it moves the existing one to the top and counts the repeat.

## Markets

A keyword's volume, CPC and difficulty are facts about a **market**, not about the phrase — "crm software" is a different business decision in the US than in Germany. Kitbase supports 142 countries, and each project has a default market you set once (Project settings → Keyword market), which every search then inherits unless you override it for that search.

Countries fall into two groups:

* **Full coverage** (94 countries) — volume, CPC, competition, difficulty and intent.
* **Volume-only coverage** (48 countries) — volume, CPC and competition, but no ranking difficulty and no search intent, because the underlying source doesn't provide them. These are priced per request rather than per row.

Which group a country is in is shown in the market picker, and the mode and clickstream controls are hidden for volume-only markets, where they don't apply.

Only the languages a country is actually served in can be selected. This isn't fussiness: the provider charges for a request with an unsupported language before rejecting it, so the combination is validated before anything is bought.

## Saved keywords

Selecting rows and saving them adds them to the project's list. **Saving is free** — the metrics you're looking at travel with the save, so nothing is re-bought to store them.

The saved list is filterable by search text, include/exclude terms, volume, CPC and difficulty ranges, and tags; sortable by any metric; and exportable. A keyword saved in two markets is two rows, with two sets of metrics, because they're two different opportunities.

### Exporting

**Export** on the results table, the saved list, or a keyword's page-one panel writes what is on screen to a **CSV file** or an **Excel file**. Nothing is re-fetched, so an export never costs credits, and it never disagrees with the table it came from. Metrics are written as numbers rather than as formatted text — competition is `46`, not `46%` — so a spreadsheet can sort and chart them straight away.

### Tags

Tags are project-level labels — "pillar", "competitor", "q3" — that you can apply in bulk from the saved list. Deleting a tag that's still on saved keywords is refused rather than silently untagging them; remove it from the keywords first, or delete it once nothing carries it.

### Refreshing metrics

Search volumes shift monthly. **Refresh metrics** re-fetches volume, CPC, difficulty and intent for every saved keyword.

This is the most expensive action in the feature: the list is grouped by market and split into batches of up to 700 keywords, one paid call each, so 5,000 saved keywords is eight calls. The estimate before you start tells you exactly how many.

It runs as a background job rather than blocking on the page, which is what makes it safe: if it's interrupted, it resumes at the batch it reached instead of paying again for the ones that already finished. Progress is shown while it runs.

## The keyword panel

Results open with the first keyword selected, and its detail sits in a column beside the table rather than in a window over it — so you can walk the list and watch the panel change instead of opening and closing something 40 times. The selected keyword is part of the URL, which means a link carries the keyword you wanted to talk about, not just the search that found it.

The panel carries only what the row cannot: the metrics stay in the table, where they can be compared against every other keyword.

**Its search trend**, up to twelve months of monthly volume, draws immediately and costs nothing: the history travelled with the search that listed the row. It answers what an average volume cannot, which is whether demand is seasonal, climbing, or already over.

**Page one** shows who currently ranks for it in that market, with each result's estimated traffic value and backlink profile — the difference between "this keyword has 2,400 searches" and "this keyword is winnable".

Live results are fetched **only when you ask for them** — selecting a keyword never buys anything, and neither does hovering one, because each lookup is a paid call. Results are cached for 12 hours across the whole install, and a page one you have already loaded is kept: coming back to that keyword shows it again for nothing, with the age of the answer stated. Keywords whose page one is already in hand carry a small marker in the results table, so you can see what is free before you select it.

## Costs and budgets

Every paid call is metered in **credits** against your organization's monthly allowance — the same pot that covers AI visibility, backlink and site data. The estimate shown before each action includes the credits you have spent this month and your monthly allowance.

When the allowance runs out, new searches are refused with a link to billing, where a credit pack extends it — but **cached results keep working**, because they cost nothing to serve.

## Permissions

| Permission | Grants |
|---|---|
| `keywords.view` | Read the saved list, tags and cost estimates. |
| `keywords.manage` | Run searches and SERP lookups, save and tag keywords, refresh metrics. |

`keywords.manage` is a spending permission, not just a writing one — it commits the organization to provider costs. Owners, admins and developers get both; analysts get `keywords.view`.

## Setup

Keyword research needs DataForSEO credentials on the server (`DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD`) — the same account that powers [AI Visibility](/ai-visibility)'s Google surfaces and the [Backlinks](/backlinks) link graph. If you already use either of those, nothing new is required. Without them, the feature reports itself as unavailable rather than failing at search time.

---

---
url: 'https://docs.kitbase.dev/workflows.md'
description: >-
  Automate the work around your site — watch for changes, analyse them, ask a
  human, and turn the answer into a draft your team can publish.
---

# Workflows

A workflow is a few steps wired together: something happens, Kitbase does some
work, and a person decides what to do with the result. They're built on the data
you already have — your pages, your traffic, your [AI Visibility](/ai-visibility)
citations — so most of them need no setup beyond choosing the steps.

::: info Nothing publishes itself
Every step that produces content produces a **draft**. If you want something to go
out, an approval step asks a person first. This is deliberate — see
[Why there is always a human](#why-there-is-always-a-human).
:::

## The shape of a workflow

Every workflow starts with exactly one **trigger** and flows forward. There are no
loops and no cycles: a workflow is a thing that happens once per event, start to
finish.

```
When a site audit finishes
        ↓
Check the content on my pages          ← AI reads them and grades them
        ↓
Only continue if… there are problems   ← stops here on a clean run
        ↓
Ask someone to approve                 ← the run pauses here
        ↓
Post to Slack
```

## Triggers

| Trigger | Fires when |
|---|---|
| On a schedule | Daily, weekly or monthly |
| Manually | You press Run |
| When a new site links to me | A referring domain sends its first visitor |
| When a link needs reclaiming | An existing backlink points at a page that now errors |
| **When a site audit finishes** | An audit has finished and been scored |
| **When new content ideas land** | A fresh batch of content recommendations is ready |
| From a webhook | Something outside Kitbase POSTs to the workflow's URL |

## Checking your own site

Two steps read your pages, and the difference between them matters.

**Check page health** grades one page at a time — title and description, canonical,
noindex, headings, structured data, whether it opens with an answer, image alt text.
It is measured rather than judged, so it is free, instant, and gives the same answer
every time.

**Check the site against itself** reads the whole site at once and looks for the
places it contradicts itself. That is a different question, and no per-page check can
answer it: if your homepage says you have four solutions and your footer lists seven,
neither page is wrong on its own — the site is. It checks

* whether your navigation lists as many things as your homepage says you have
* whether your header and footer classify the same group the same way
* whether a figure like a match rate is stated one way on one page and another way
  elsewhere
* whether links in your navigation send visitors to another company's domain
* whether any pages are linked from nowhere
* whether template sample pages are still live, and whether your sitemap is offering
  them up to be read

Both are free and neither uses AI credits.

One related check does cost credits: **Analyze with AI → Find pages that compete** reads your
pages and groups the ones answering the same buyer question. That one needs a model, because two
pages competing for one question usually share no wording at all — the overlap is in what the
buyer meant. Wire it as *My site pages → Fetch the page → Analyze with AI*.

## Asking a person

The **Ask someone to approve** step pauses the run. Everything after it waits until
somebody decides — which can be minutes or days. The run isn't holding anything
open while it waits; it's parked, and it picks up exactly where it left off.

You choose:

* **Who decides.** One person is usually right. Requiring everyone to approve is
  what makes approvals slow.
* **What happens if nobody does.** Every approval has a deadline, because a request
  nobody answers is how work quietly disappears. When it runs out, the workflow
  either stops that branch (the default) or carries on.

There are three answers:

| Answer | What happens |
|---|---|
| **Approve** | The run continues down the approved branch |
| **Request changes** | The run takes the other branch, and your note is recorded |
| **Reject** | The run takes the other branch |

"Request changes" is its own answer, not a polite rejection — it's recorded
separately so you can tell the difference later between work that was turned down
and work that was sent back.

Anything waiting on you appears under **Workflows → Approvals**. If two people
answer at the same moment, the first one counts and the second is told what
happened.

## Drafts

The **Create a draft** step turns what a workflow produced into something a person
can open, edit and publish, under **Drafts**.

A draft moves through: `Draft → In review → Approved → Published`, with
`Changes requested` sending it back. Every save keeps the previous version, so you
can always see what the model originally wrote next to what you actually shipped —
revisions written by a workflow are marked as such rather than attributed to a
person.

If two people edit the same draft, the second one to save is told so, and their
work stays on screen rather than being silently overwritten.

### Checking a draft before it goes out

**Review against my site** reads a draft next to everything you have already
published and answers one question: would putting this out make the site say two
things at once? It reports

* a figure the draft states that your site already states differently
* a count of your own structure that disagrees with your homepage
* a reserved word — "solution", "product" — attached to something your site does not
  classify that way
* a title a live page already carries, which would leave two pages answering one
  question

It comes back **Clear**, **Worth a look**, or **Contradicts the site**, with the
place your site already says otherwise named so you know where to go. It reports
only — nothing is blocked, and the call stays yours.

You can also paste or upload text that is not a draft yet and get the same check.

## Sending the result somewhere

* **Post to Slack** — into a channel you pick. Connect Slack under
  Settings → Integrations first.
* **Send an email** — to the people you list.
* **In-app notice** — a notification in the dashboard.

## When a run delivers nothing

A step that finds nothing to pass on stops the workflow there, on purpose. **Backlink
gaps** with no gaps to report, a **page check** with nothing changed, a filter that
removed every row — each of them settles as **Skipped**, and everything after it is
skipped too. That is why you do not get a Slack message reading "here are your 0
backlink gaps".

Open the run and each step says what it did in its own words, under its name: *found
12 backlink gap(s)*, *no backlink gaps found across 4 scan(s)*, *no AI visibility
scans to read citations from yet — run one first*. That line is where the reason
lives, and it distinguishes the two silences worth telling apart: there was nothing
to report, or the data this step reads has not been collected yet.

The reason sits on the step that made the decision. Steps further down the chain read
only **Skipped** with no line of their own — they never ran, so they have nothing to
say. Read upward to the first skipped step to find out why the run ended.

## Why there is always a human

Publishing AI-written pages without anyone reading them reliably works for about
two months and then stops working. The pattern is well documented: pages get
indexed, rankings appear, and then they decay to nothing over the following year —
by which point there are hundreds of them. Google's guidance is explicit that
generating many pages without adding value is spam regardless of how they were
produced, and that the thing which distinguishes acceptable AI-assisted content is
human oversight.

So Kitbase will draft for you, but it won't publish for you. The approval step and
the drafts queue exist to make the review quick, not optional.

## Limits

| | Starter | Pro | Business |
|---|---|---|---|
| Workflow runs per month | 100 | 400 | Unlimited |
| Active workflows | 10 | 10 | 10 |
| Steps per workflow | 15 | 15 | 15 |

AI steps cost credits based on what they actually spend. Every run reserves its
estimated cost up front and settles to the real figure when it finishes, and a
single step can't run away with your monthly budget. A manual run shows its
credit estimate before it starts. A scheduled or webhook workflow cannot ask you
per run, so when you publish one with AI steps you accept the per-run estimate
and set a **monthly credit budget** for that workflow (or choose unlimited —
an explicit choice); runs that would exceed it are refused and you are notified.
The workflow runs themselves never use credits — only the AI steps inside them.

---

---
url: 'https://docs.kitbase.dev/api-reference.md'
description: >-
  Complete REST API reference for Kitbase — OpenAPI spec, authentication and API
  keys, permissions, the error model, rate-limit headers, versioning and
  deprecation policy, and the SDK ingestion endpoints.
---

# API Reference

REST API reference for the Kitbase SDK endpoints, plus the conventions — authentication, errors, rate limits, versioning — that every Kitbase API operation follows.

## OpenAPI specification

The full public surface (the same operations the [CLI](/cli) and dashboard use) is published as an OpenAPI 3.0 document. Every operation has a unique `operationId`, a description, typed parameters, response schemas and typed error responses, so it can be loaded straight into an API client, a code generator or an LLM's function-calling tool set.

| Format | URL |
|--------|-----|
| JSON | `https://api.kitbase.dev/openapi.json` (mirrored at `https://kitbase.dev/openapi.json`) |
| YAML | `https://api.kitbase.dev/openapi.yaml` (mirrored at `https://kitbase.dev/openapi.yaml`) |

Both are served anonymously with `Cache-Control: public, max-age=3600`, an `ETag`, and permissive CORS.

```bash
curl -s https://api.kitbase.dev/openapi.json | jq '.info.version, (.paths | length)'
```

## Base URL

```
https://api.kitbase.dev
```

Self-hosted deployments serve the API under `https://<your-host>/api`.

## Authentication

| Credential | Header | Used by |
|------------|--------|---------|
| **SDK key** (`pk_kitbase_…`) | `x-sdk-key: pk_kitbase_…` | The `/sdk/v1/*` ingestion endpoints below (browser SDKs, tracking script) |
| **Private API key** (`sk_kitbase_…`) | `Authorization: Bearer sk_kitbase_…` or `X-API-Key: sk_kitbase_…` | Everything else: the CLI in CI, server-side ingestion (`/ingest/v1/*`), the MCP server, your own scripts |
| **User session** (JWT) | `Authorization: Bearer <jwt>` | The dashboard and the CLI's browser login |

SDK endpoints use the `x-sdk-key` header:

```
x-sdk-key: <YOUR_SDK_KEY>
```

### Permissions and scoping

Every operation is guarded by a named permission (for example `analytics.view`, `webhook.create`, `aivisibility.manage`). A user holds the permissions of their role in the organization — owner, admin, developer, analyst or support. A private API key is created by a user and holds **that user's live permissions, limited to the key's project**; it can never create or delete credentials (`private_api_key.*`, `sdk_key.*`). Revoking a role or a key takes effect on the next request. A permission failure is a `403` with error code `PERM_001`.

The [MCP server](/sdks/mcp) is authorized with OAuth 2.1 (PKCE). At consent time the user picks the organization, the project and the exact subset of permissions the connection may use; each tool call is then checked against that subset intersected with the user's live permissions.

***

## Events

### Track Event

Track an event in your application.

```
POST /sdk/v1/logs
```

#### Headers

| Header | Required | Description |
|--------|----------|-------------|
| `x-sdk-key` | Yes | Your Kitbase SDK key |
| `Content-Type` | Yes | `application/json` |

#### Request Body

```json
{
  "event": "New Subscription",
  "channel": "payments",
  "user_id": "user-123",
  "anonymous_id": "550e8400-e29b-41d4-a716-446655440000",
  "icon": "💰",
  "notify": true,
  "description": "User subscribed to premium plan",
  "timestamp": 1705321800000,
  "tags": {
    "plan": "premium",
    "amount": 9.99
  }
}
```

#### Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event` | `string` | Yes | Event name |
| `channel` | `string` | Yes | Event channel/category |
| `user_id` | `string` | No | Identified user ID |
| `anonymous_id` | `string` | No | Anonymous user ID (UUID) |
| `icon` | `string` | No | Emoji icon |
| `notify` | `boolean` | No | Send real-time notification |
| `description` | `string` | No | Event description |
| `timestamp` | `number` | No | Unix timestamp in ms |
| `tags` | `object` | No | Key-value metadata |

#### Response

**Status: `202 Accepted`**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "New Subscription",
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

#### Errors

| Status | Description |
|--------|-------------|
| `400` | Invalid parameters |
| `401` | Missing or invalid SDK key |
| `503` | Queue full |

***

### Server-Side Crawler Detection

Detect crawlers and AI bots that **never run the JavaScript SDK** (GPTBot, Googlebot, ClaudeBot, scrapers, …). Install lightweight middleware on your server or edge that forwards each request's signals; Kitbase classifies the actor server-side and stores bot/crawler traffic with full attribution.

```
POST /ingest/v1/server
```

**Authentication:** this is a server-to-server endpoint, so it uses your **secret API key** (`sk_kitbase_…`), sent as `Authorization: Bearer <API_KEY>` (or `X-API-Key`) — never the browser-exposed SDK key. The key is bound to a project, which is the target for everything you send. This is the generic source in the ingestion family at `/ingest/v1/{source}`; per-vendor log-drain endpoints (`/ingest/v1/vercel`, `/ingest/v1/cloudfront`, `/ingest/v1/netlify`, `/ingest/v1/fastly`, …) are added under the same namespace over time.

> **Why this exists:** tag-based analytics only sees clients that execute JS, so non-JS crawlers are invisible. This endpoint observes them in your request path. **Human requests are ignored** here (the JS SDK already counts them, so this avoids double-counting); detected bot/crawler requests are stored whenever events are enabled for the project. Forwarded human traffic is classified in memory and discarded — not stored; for stored bot events, the raw IP is kept only when IP logging is enabled for the project.

#### Request Body

Send the **original visitor's** signals (not your server's connection):

```json
{
  "events": [
    {
      "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot",
      "ip_address": "203.0.113.5",
      "method": "GET",
      "host": "example.com",
      "path": "/pricing",
      "referrer": "https://www.google.com/",
      "signature": "...",
      "signature_input": "...",
      "signature_agent": "https://chatgpt.com",
      "client_timestamp": 1705321800000
    }
  ]
}
```

#### Parameters (per item)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `user_agent` | `string` | Yes | Original request `User-Agent` |
| `ip_address` | `string` | Yes | Original client IP |
| `method` | `string` | No | HTTP method (used for Web Bot Auth signature base) |
| `host` | `string` | No | Original host/authority |
| `path` | `string` | No | Original request path |
| `referrer` | `string` | No | Original `Referer` |
| `signature`, `signature_input`, `signature_agent` | `string` | No | Web Bot Auth headers, if present — enables cryptographic verification |
| `client_timestamp` | `number` | No | Observation time (ms); defaults to receipt time |
| `event` | `string` | No | Event name; defaults to `server_request` |

#### Response

**Status: `202 Accepted`** — `accepted` counts how many were stored (bots); humans/disabled are silently skipped.

```json
{ "accepted": 1, "total": 1 }
```

Stored rows carry the attribution fields documented in [Server-Side Tag Enrichment](/track-events#bot-crawler-attribution) (`actor_type`, `bot_name`, `bot_vendor`, `actor_verified`, `verification_method`, etc.) and are flagged `is_bot` so they're excluded from human visitor and billing counts. (Surfacing these as dedicated dashboard filter dimensions is incremental.)

#### Platform setup guides

Copy-paste setup for each platform lives under **[Bot & Crawler Detection](/crawler-detection)** — pick yours:

> Batch requests (up to 500 per call) and send fire-and-forget so analytics never adds latency to your responses.

***

### Vercel Log Drain

Hosted on Vercel? Point a **Log Drain** at Kitbase to capture every request — including crawlers that never run JS — with zero code.

```
POST /ingest/v1/vercel
```

Vercel POSTs batches of request logs (JSON array or NDJSON); Kitbase reads each log's `proxy` object (`clientIp`, `userAgent`, `method`, `host`, `path`, `referer`), classifies the actor, and stores bot/crawler requests (humans ignored). The drain authenticates with your project's secret key (as a custom `Authorization: Bearer` header), which resolves the target project.

**`200 OK`** — `{ "accepted": <stored bots>, "received": <request logs parsed> }`. Non-request logs (build/function output) are ignored.

See the [Vercel setup guide](/crawler-detection/vercel) for step-by-step Log Drain configuration. The same per-vendor pattern extends to other hosts (CloudFront, Netlify, Fastly) under `/ingest/v1/<vendor>`.

***

### AWS CloudFront Standard Logs

Served through **AWS CloudFront** (including **AWS Amplify** sites)? Stream CloudFront **standard logs (v2)** to Kitbase through **Amazon Data Firehose** to capture every request — including crawlers that never run JS — with zero code.

```
POST /ingest/v1/cloudfront
```

Firehose POSTs batched log records (base64 envelope, JSON output format); Kitbase decodes each CloudFront log's fields (`c-ip`, `cs(User-Agent)`, `cs-method`, `cs(Host)`, `cs-uri-stem`, `cs(Referer)`), classifies the actor, and stores bot/crawler requests (humans ignored). The stream authenticates with your project's **secret** key, which Firehose sends in the `X-Amz-Firehose-Access-Key` header and which resolves the target project.

**`200 OK`** — Firehose's required acknowledgement, `{ "requestId": "…", "timestamp": <ms> }`. Rows without a usable IP + User-Agent are ignored; a non-2xx makes Firehose retry then back up to S3.

See the [AWS CloudFront setup guide](/crawler-detection/cloudfront) for the CloudFront + Firehose configuration.

***

### Identify User

Link an anonymous user to an identified user.

```
POST /sdk/v1/identify
```

#### Request Body

```json
{
  "anonymous_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user-123",
  "traits": {
    "email": "user@example.com",
    "plan": "premium"
  }
}
```

#### Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `anonymous_id` | `string` | Yes | Anonymous user ID to link |
| `user_id` | `string` | Yes | Identified user ID |
| `traits` | `object` | No | User properties |

#### Response

**Status: `200 OK`**

```json
{
  "success": true
}
```

***

## Tag Enrichment

Events are automatically enriched with these tags:

| Tag | Description |
|-----|-------------|
| `__browser` | Browser name |
| `__browser_version` | Browser version |
| `__os` | Operating system |
| `__os_version` | OS version |
| `__device` | Device type |
| `__country` | Country code |
| `__region` | Region/State |
| `__city` | City |
| `__session_id` | Session ID |
| `__path` | Page path |
| `__referrer` | Referrer URL |
| `__utm_source` | UTM source |
| `__utm_medium` | UTM medium |
| `__utm_campaign` | UTM campaign |

***

## HTTP Status Codes

| Code | Description |
|------|-------------|
| `200` | Success |
| `202` | Accepted (queued) |
| `400` | Invalid parameters |
| `401` | Missing or invalid credential |
| `403` | Authenticated, but not permitted to do this |
| `404` | Not found (or not visible to this credential) |
| `409` | Conflict with existing state |
| `429` | Rate limited — see [Rate Limits](#rate-limits) |
| `5xx` | Unexpected server error |

`401` and `403` mean different things and are worth handling differently: `401` says the credential is absent, malformed or expired — presenting a valid one will work. `403` says the credential was accepted and still may not perform this action, so retrying with the same key never helps. A log drain that receives `401` should check that its key is actually being sent.

## Error Response

Every non-2xx response — from any endpoint, including authentication failures raised before a request reaches a handler — has the same JSON body, the `ErrorResponse` schema in the [OpenAPI spec](#openapi-specification):

```json
{
  "error": {
    "code": "AUTH_003",
    "message": "Authentication required",
    "details": {}
  },
  "timestamp": "2026-08-22T10:45:52.855Z"
}
```

| Field | Meaning |
|-------|---------|
| `error.code` | Stable, machine-readable identifier. Branch on this, not on `message`. Families: `AUTH_*`, `PERM_*`, `VAL_*`, `ORG_*`, `PROJECT_*`, `BILLING_*`, `WF_*`, … |
| `error.message` | Human-readable explanation; may change without notice |
| `error.details` | Typed extras when they exist — `field`, `value`, `resource`, `reason`, `retryAfterSeconds` |
| `timestamp` | When the error was produced (RFC 3339) |

## Rate Limits

Authenticated requests are limited **per credential** (user, private API key or MCP connection) to **1,000 requests per minute** in a fixed one-minute window. Every response carries the IETF rate-limit headers plus the legacy `X-RateLimit-*` trio, so a client can throttle itself before it is throttled:

```
RateLimit-Policy: "per-minute";q=1000;w=60
RateLimit: "per-minute";r=997;t=42
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 42
```

| Header | Meaning |
|--------|---------|
| `RateLimit-Policy` | The policy: quota `q` requests per window `w` seconds |
| `RateLimit` | Live state: `r` requests remaining, `t` seconds until the window resets |
| `X-RateLimit-Limit` / `-Remaining` / `-Reset` | The same three numbers, in the older de-facto format |

Over the limit, the response is `429` with the standard [error body](#error-response) (`AUTH_014`) and a `Retry-After` header in seconds. Public, unauthenticated endpoints (`/public/*`) have their own stricter per-IP limits and answer `429` + `Retry-After` the same way. Event ingestion (`/sdk/v1/*`, `/ingest/v1/*`) is not subject to the per-credential limit.

## Versioning and Deprecation

The API is **version 1** (`info.version` in the spec). Paths are stable and changes are additive: new fields, parameters and endpoints may appear at any time, and clients must ignore fields they do not recognise. Breaking changes ship under a new path prefix (`/v2/…`) rather than by changing an existing operation.

An operation scheduled for removal is marked `deprecated: true` in the OpenAPI spec at least **90 days** before its sunset, and during that period every response from it carries:

```
Deprecation: @1767225600
Sunset: Wed, 01 Apr 2026 00:00:00 GMT
Link: <https://docs.kitbase.dev/changelog/>; rel="deprecation"; type="text/html"
```

`Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) is the date the deprecation was announced, `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) the date after which the operation may stop working, and the `Link` points at the migration notes. Changes are announced in the [changelog](/changelog/).

## Next steps

* [OpenAPI spec](https://api.kitbase.dev/openapi.json) — the complete, machine-readable public surface.
* [MCP Server](/sdks/mcp) — the same data and actions for AI assistants, with a server card for discovery.
* [CLI](/cli) — every endpoint here is also a `kitbase` command.
* [SDKs & Tools](/sdks/) — typed SDKs that wrap this API.
* [Bot & Crawler Detection](/crawler-detection) — platform guides for the server-side ingestion endpoint.

---

---
url: 'https://docs.kitbase.dev/error-handling.md'
description: >-
  Error types, retry patterns, and best practices for handling errors across all
  Kitbase SDKs.
---

# Error Handling

Learn how to handle errors gracefully when using the Kitbase SDK.

## Overview

The TypeScript SDKs provide typed error classes that allow you to handle specific error conditions precisely. This enables you to provide better user experiences and implement robust retry logic.

## Error Types

### Events Errors

| Error | HTTP Status | Description |
|-------|-------------|-------------|
| `AuthenticationError` | 401 | Invalid or missing API key |
| `ValidationError` | 400/422 | Missing or invalid required fields |
| `TimeoutError` | - | Request exceeded timeout (30s) |
| `ApiError` | 4xx/5xx | API returned an error response |

***

## TypeScript

### Events Error Handling

```typescript
import {
  init,
  KitbaseError,
  AuthenticationError,
  ApiError,
  ValidationError,
  TimeoutError,
} from '@kitbase/analytics';

const kitbase = init({ sdkKey: '<YOUR_API_KEY>' });

try {
  await kitbase.track({
    channel: 'payments',
    event: 'New Subscription',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key - check your sdkKey
    console.error('Authentication failed');
  } else if (error instanceof ValidationError) {
    // Missing required fields
    console.error(`Validation error: ${error.field}`);
  } else if (error instanceof TimeoutError) {
    // Request timed out - retry later
    console.error('Request timed out');
  } else if (error instanceof ApiError) {
    // API returned an error
    console.error(`API error: ${error.statusCode}`);
    console.error(error.response);
  } else if (error instanceof KitbaseError) {
    // Generic SDK error
    console.error(error.message);
  }
}
```

### Retry with Exponential Backoff

```typescript
import type { TrackOptions, TrackResponse } from '@kitbase/analytics';
import { TimeoutError, ApiError } from '@kitbase/analytics';

async function trackWithRetry(
  kitbase: Kitbase,
  options: TrackOptions,
  retries = 3
): Promise<TrackResponse> {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      return await kitbase.track(options);
    } catch (error) {
      // Don't retry auth or validation errors
      if (error instanceof AuthenticationError) throw error;
      if (error instanceof ValidationError) throw error;

      // Retry on timeout or server errors
      const shouldRetry =
        error instanceof TimeoutError ||
        (error instanceof ApiError && error.statusCode >= 500);

      if (shouldRetry && attempt < retries) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }

      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}
```

***

## Error Properties

### TypeScript

#### `AuthenticationError`

```typescript
interface AuthenticationError extends KitbaseError {
  message: string; // "Invalid or missing API key"
}
```

#### `ValidationError`

```typescript
interface ValidationError extends KitbaseError {
  message: string; // Error description
  field: string;   // The field that failed validation
}
```

#### `TimeoutError`

```typescript
interface TimeoutError extends KitbaseError {
  message: string; // "Request timed out"
}
```

#### `ApiError`

```typescript
interface ApiError extends KitbaseError {
  message: string;      // Error description from API
  statusCode: number;   // HTTP status code
  response: unknown;    // Raw response body
}
```

## Best Practices

### 1. Don't Retry Authentication Errors

Authentication errors indicate a configuration problem. Log these prominently and don't retry:

```typescript
if (error instanceof AuthenticationError) {
  logger.error('Kitbase authentication failed - check API key');
  notifyOps('Kitbase API key is invalid');
  throw error; // Don't retry
}
```

### 2. Implement Exponential Backoff

For transient errors (timeouts, server errors), use exponential backoff:

```typescript
const delay = Math.min(Math.pow(2, attempt) * 1000, 30000); // Max 30s
await new Promise(resolve => setTimeout(resolve, delay));
```

### 3. Log Errors for Debugging

Include context when logging errors:

```typescript
} catch (error) {
  logger.error('Failed to track event', {
    channel: options.channel,
    event: options.event,
    error: error instanceof KitbaseError ? {
      type: error.constructor.name,
      message: error.message,
    } : error,
  });
}
```

### 4. Graceful Degradation

Don't let tracking failures break your application:

```typescript
async function safeTrack(options: TrackOptions) {
  try {
    await kitbase.track(options);
  } catch (error) {
    // Log but don't throw - tracking is non-critical
    console.error('Event tracking failed:', error);
  }
}
```

### 5. Validate Before Sending

Catch validation errors early:

```typescript
function validateTrackOptions(options: TrackOptions): void {
  if (!options.channel?.trim()) {
    throw new Error('Channel is required');
  }
  if (!options.event?.trim()) {
    throw new Error('Event is required');
  }
}
```

## Next steps

* [JavaScript SDK error types](/sdks/javascript#error-types) — the full typed error hierarchy.
* [Track Events](/track-events) — the calls these errors come from.
* [API reference](/api-reference#http-status-codes) — status codes and rate limits.

---

---
url: 'https://docs.kitbase.dev/changelog.md'
description: >-
  What changed in Kitbase, week by week — new features, improvements, fixes, and
  API deprecation notices.
---

# Changelog

What changed in Kitbase, week by week. This is also where API changes are announced: an operation that is going away is listed here at least 90 days before its sunset, alongside the `Deprecation` and `Sunset` headers it starts sending — see [Versioning and Deprecation](/api-reference#versioning-and-deprecation).

## Weeks

* [Week 8, 2026](/changelog/2026-W08) — Frustration signals, funnels, environment settings, organization switcher, unique paths & event names API.
* [Week 7, 2026](/changelog/2026-W07) — the week of February 9, 2026.

## API deprecations

None scheduled. When one is, it appears here with the operation's `operationId`, the sunset date and the migration path.

## Next steps

* [API Reference](/api-reference) — the conventions every operation follows.
* [OpenAPI spec](https://api.kitbase.dev/openapi.json) — deprecated operations are flagged `deprecated: true` here.

---

---
url: 'https://docs.kitbase.dev/changelog/2026-W08.md'
description: 'What''s new in Kitbase for the week of February 16, 2026.'
---

## What's New -- Week of February 16, 2026

### New Features

* **Frustration Signals Analytics** -- Kitbase now detects and tracks rage clicks, dead clicks, and computes a frustration score for each session. See frustration data on the Sessions page with a new score column and icon, and use it to find the sessions where users struggled most.

* **Frustration Detection SDK Plugin** -- The SDK now includes an `autoDetectFrustration` option that automatically captures rage clicks and dead clicks on the client side -- no manual instrumentation required.

* **Environment Settings** -- A new environment-level settings system lets you configure behavior per environment (e.g., staging vs. production) instead of per project.

* **Funnel Management** -- Build and manage conversion funnels directly in the dashboard. Define multi-step funnels from your tracked events and pages, then visualize drop-off between each step.

* **Organization Switcher** -- Quickly switch between organizations from the app header without navigating away from your current page.

* **Unique Paths & Event Names API** -- New API endpoints return the distinct page paths and custom event names recorded in your environment, making it easier to build filters and funnels.

***

### Improvements

* **Timezone-Aware Analytics** -- All analytics queries now respect your selected timezone. Date ranges, groupings, and charts reflect local time instead of UTC.

* **Better Element Visibility Tracking** -- The Session Events Timeline now shows when elements enter and leave the viewport, giving you richer context when reviewing session activity.

* **Improved Session Search** -- Searching sessions by session ID, user ID, or anonymous ID now works reliably even when IDs contain hyphens.

* **More Accurate Session Duration** -- Session duration is now correctly reported in milliseconds across the Users analytics view.

* **Better Session Event Ordering** -- The `session_start` event timestamp is now placed just before the first real event, ensuring correct chronological ordering in timelines.

* **Enhanced Custom Event Details** -- Custom event analytics now include additional fields and the raw URL, giving you a more complete picture of each event's context.

* **Enhanced Event Detail Page** -- The event detail view in the dashboard has been redesigned with new features and a cleaner UI.

* **Refreshed Marketing Site** -- New "Why Kitbase?" and "Use Cases" pages explain the product's value proposition and real-world applications.

***

### Bug Fixes

* **Invitation Flow** -- Fixed an issue where the invitation service could fail when the logged-in user's email was unavailable.

* **Journey & Funnel Queries** -- Fixed path normalization and trailing slash handling in journey analytics, and simplified funnel query path conditions for more reliable results.

* **Dashboard Cleanup** -- Removed deprecated event status queries and unused code across multiple dashboard pages.

***

---

---
url: 'https://docs.kitbase.dev/changelog/2026-W07.md'
description: 'What''s new in Kitbase for the week of February 9, 2026.'
---

## What's New -- Week of February 2, 2026

### New Features

* **Session Analytics** -- See exactly how users interact with your product. Browse session summaries, drill into individual sessions, and view every event that happened during a visit -- including duration, pages viewed, and location.

* **User Analytics** -- Get a detailed profile for every user. A new per-user detail page shows activity breakdowns, user type, and geographic data with improved country recognition on the world map.

* **Richer Event Insights** -- Custom event analytics now return deeper, more detailed data, giving you a clearer picture of how your events are performing.

***

### Improvements

* **Visual Polish** -- Event lists now display country flags and browser icons at a glance, making it easier to scan geographic and device data across analytics and event tables.

* **Smoother Login Experience** -- Signing in, completing signup, and verifying two-factor authentication all navigate you to the right organization more reliably. Token handling is more robust across the board.

* **More Accurate Analytics** -- Session and web analytics numbers are now more precise, eliminating edge cases where duplicate or stale data could appear in reports.

* **Faster Performance** -- Behind-the-scenes caching improvements make the dashboard and API more responsive, especially under load.

* **Easier Self-Hosting** -- A new standalone deployment option makes it simpler to run the Kitbase dashboard on your own infrastructure with minimal configuration.

* **Simpler Identity Resolution** -- Linking anonymous visitors to known users is now faster and more straightforward, with a cleaner data model under the hood.

***

### Bug Fixes

* **Activity Heatmap** -- Fixed a crash that could occur when heatmap data was incomplete.

* **Session Duration Display** -- Resolved an issue where session duration metrics could display incorrectly in certain edge cases.

***

---

---
url: 'https://docs.kitbase.dev/import-data.md'
description: >-
  Backfill your Kitbase project with historical analytics imported from Google
  Analytics 4, so your dashboards show data from before you switched.
---

# Import Data

Bring your history with you. The import module backfills a Kitbase project with
analytics from another platform so your dashboards show data from before you
switched. The first supported source is **Google Analytics 4 (GA4)**.

Imports are a one-time backfill over a date range you choose. They run in the
background, survive restarts, and can be re-run after deleting the old data.

## Connect Google Analytics

1. Open a project, go to **Settings**, and select the **Import** tab.
2. Click **Connect Google Analytics** and grant Kitbase **read-only** access
   (the `analytics.readonly` scope). Kitbase never writes to your GA4 account.
3. One Google account is connected per organization. Disconnect any time from the
   same page or from **Organization → Integrations**.

## Run an import

1. Pick a **GA4 property** from the connected account.
2. Choose a **start** and **end** date. The end date must be before today —
   the current day is still incomplete in GA4.
3. Click **Start import**. Progress shows day-by-day; you can leave the page.

Imported data lands in the same tables as live tracking, so **every existing
dashboard** (Web Analytics, top pages, sources, devices, countries) includes it
automatically over the imported range.

## What gets imported, and how accurate it is

GA4's API exposes **aggregated reports** (metrics grouped by dimensions per day),
not raw events. Kitbase expands those aggregates into per-session events, one day
at a time. That means:

| Metric | Accuracy |
| --- | --- |
| **Pageviews** (per page, per day) | **Exact** — matches GA4's "Views". |
| **Sessions** (total, and per source / device / country) | **Exact** (within GA4's own rounding). |
| **Unique visitors** | **Approximated.** Per-day visitor counts are close; weekly/monthly uniques run slightly high because GA4 de-duplicates visitors across days and an aggregate import cannot. |
| **Bounce rate, average session duration** | Reconstructed from GA4's daily figures. |
| **Referrers** | Shown as GA4 **source names** (e.g. `google`), not full referring URLs. |

A few things to know:

* **Time zone.** GA4 days are labelled in your property's time zone but stored in
  Kitbase as UTC days, so day boundaries can differ slightly from the GA4 UI if
  you view dashboards in another time zone.
* **Speed.** Google limits how fast historical data can be read. Multi-year
  imports can take a while and may pause and resume as quotas refill — this is
  normal; the import continues on its own.
* **Billing.** Imported events **do not** count toward your monthly event or
  session limits.

## Delete imported data

Each import in the history list has a **Delete data** action. It removes every
event and session that import wrote, and frees the date range to be imported
again. Deletion runs in the background and can take a few minutes to reflect in
dashboards.

To re-import a range you already imported, delete the existing import's data
first — overlapping imports are rejected to avoid double-counting.

## Permissions

* Connecting or disconnecting a source needs the **integration** create/delete
  permission (Owner, Admin).
* Starting, cancelling, or deleting an import needs **dataimport.manage**
  (Owner, Admin, Developer). Viewing imports needs **dataimport.view** (also
  Analyst).